DOC: Use sphinxcontrib-apidoc and various cleanups

[effigies]

Was testing out #1007, and I don't think that was done correctly. I've built on it. Hopefully each individual commit is self-explanatory, but, to summarize:

1. I removed the existing apidocs/ contents and added .gitignore so that they won't accidentally get readded.
2. I used the sphinxcontrib-apidoc, and pointed it at the old apidocs/ directory for continuity.
3. Added dependencies to the docs/sphinx-requirements.txt and an "extra" so pip install rdflib[docs] will get you what you need.
4. Various cleanups to address some warnings while building.

Expand for current output:

$ make clean && make html      
rm -rf _build/*
sphinx-build -b html -d _build/doctrees   . _build/html
Running Sphinx v2.4.4
making output directory... done
Creating file /home/cjmarkie/Projects/rdflib/docs/apidocs/rdflib.rst.
Creating file /home/cjmarkie/Projects/rdflib/docs/apidocs/rdflib.extras.rst.
Creating file /home/cjmarkie/Projects/rdflib/docs/apidocs/rdflib.plugins.rst.
Creating file /home/cjmarkie/Projects/rdflib/docs/apidocs/rdflib.plugins.parsers.rst.
Creating file /home/cjmarkie/Projects/rdflib/docs/apidocs/rdflib.plugins.serializers.rst.
Creating file /home/cjmarkie/Projects/rdflib/docs/apidocs/rdflib.plugins.sparql.rst.
Creating file /home/cjmarkie/Projects/rdflib/docs/apidocs/rdflib.plugins.sparql.results.rst.
Creating file /home/cjmarkie/Projects/rdflib/docs/apidocs/rdflib.plugins.stores.rst.
Creating file /home/cjmarkie/Projects/rdflib/docs/apidocs/rdflib.tools.rst.
Creating file /home/cjmarkie/Projects/rdflib/docs/apidocs/modules.rst.
loading intersphinx inventory from https://docs.python.org/3.7/objects.inv...
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 22 source files that are out of date
updating environment: [new config] 32 added, 0 changed, 0 removed
reading sources... [100%] utilities                                                                                                                                                                                                                                                                                           
/home/cjmarkie/Projects/rdflib/examples/film.py:docstring of examples.film:15: WARNING: Unexpected indentation.
/home/cjmarkie/Projects/rdflib/rdflib/extras/external_graph_libs.py:docstring of rdflib.extras.external_graph_libs.rdflib_to_graphtool:9: WARNING: Unexpected indentation.
/home/cjmarkie/Projects/rdflib/rdflib/extras/external_graph_libs.py:docstring of rdflib.extras.external_graph_libs.rdflib_to_graphtool:10: WARNING: Block quote ends without a blank line; unexpected unindent.
/home/cjmarkie/Projects/rdflib/rdflib/extras/external_graph_libs.py:docstring of rdflib.extras.external_graph_libs.rdflib_to_graphtool:12: WARNING: Unexpected indentation.
/home/cjmarkie/Projects/rdflib/rdflib/extras/external_graph_libs.py:docstring of rdflib.extras.external_graph_libs.rdflib_to_graphtool:15: WARNING: Block quote ends without a blank line; unexpected unindent.
/home/cjmarkie/Projects/rdflib/rdflib/extras/external_graph_libs.py:docstring of rdflib.extras.external_graph_libs.rdflib_to_graphtool:18: WARNING: Definition list ends without a blank line; unexpected unindent.
/home/cjmarkie/Projects/rdflib/rdflib/extras/external_graph_libs.py:docstring of rdflib.extras.external_graph_libs.rdflib_to_networkx_digraph:12: WARNING: Unexpected indentation.
/home/cjmarkie/Projects/rdflib/rdflib/extras/external_graph_libs.py:docstring of rdflib.extras.external_graph_libs.rdflib_to_networkx_digraph:12: WARNING: Inline strong start-string without end-string.
/home/cjmarkie/Projects/rdflib/rdflib/extras/external_graph_libs.py:docstring of rdflib.extras.external_graph_libs.rdflib_to_networkx_graph:12: WARNING: Unexpected indentation.
/home/cjmarkie/Projects/rdflib/rdflib/extras/external_graph_libs.py:docstring of rdflib.extras.external_graph_libs.rdflib_to_networkx_graph:12: WARNING: Inline strong start-string without end-string.
/home/cjmarkie/Projects/rdflib/rdflib/extras/external_graph_libs.py:docstring of rdflib.extras.external_graph_libs.rdflib_to_networkx_multidigraph:9: WARNING: Unexpected indentation.
/home/cjmarkie/Projects/rdflib/rdflib/extras/external_graph_libs.py:docstring of rdflib.extras.external_graph_libs.rdflib_to_networkx_multidigraph:9: WARNING: Inline strong start-string without end-string.
/home/cjmarkie/Projects/rdflib/rdflib/extras/infixowl.py:docstring of rdflib.extras.infixowl.Class:10: WARNING: Unexpected indentation.
/home/cjmarkie/Projects/rdflib/rdflib/extras/infixowl.py:docstring of rdflib.extras.infixowl.Property:5: WARNING: Block quote ends without a blank line; unexpected unindent.
/home/cjmarkie/Projects/rdflib/rdflib/extras/infixowl.py:docstring of rdflib.extras.infixowl.Restriction:4: WARNING: Block quote ends without a blank line; unexpected unindent.
/home/cjmarkie/Projects/rdflib/rdflib/plugins/stores/sparqlstore.py:docstring of rdflib.plugins.stores.sparqlstore.SPARQLStore.triples:12: WARNING: Unexpected indentation.
/home/cjmarkie/Projects/rdflib/rdflib/plugins/stores/sparqlstore.py:docstring of rdflib.plugins.stores.sparqlstore.SPARQLStore.triples:15: WARNING: Block quote ends without a blank line; unexpected unindent.
/home/cjmarkie/Projects/rdflib/rdflib/plugins/stores/sparqlstore.py:docstring of rdflib.plugins.stores.sparqlstore.SPARQLStore.triples:17: WARNING: Content block expected for the "warning" directive; none found.
/home/cjmarkie/Projects/rdflib/rdflib/plugins/stores/sparqlstore.py:docstring of rdflib.plugins.stores.sparqlstore.SPARQLStore.triples:18: WARNING: Explicit markup ends without a blank line; unexpected unindent.
/home/cjmarkie/Projects/rdflib/rdflib/plugins/stores/sparqlstore.py:docstring of rdflib.plugins.stores.sparqlstore.SPARQLStore.triples:19: WARNING: Bullet list ends without a blank line; unexpected unindent.
/home/cjmarkie/Projects/rdflib/rdflib/plugins/stores/sparqlstore.py:docstring of rdflib.plugins.stores.sparqlstore.SPARQLStore.triples:28: WARNING: Unexpected indentation.
/home/cjmarkie/Projects/rdflib/rdflib/plugins/stores/sparqlstore.py:docstring of rdflib.plugins.stores.sparqlstore.SPARQLStore.triples:29: WARNING: Block quote ends without a blank line; unexpected unindent.
/home/cjmarkie/Projects/rdflib/rdflib/plugins/stores/sparqlstore.py:docstring of rdflib.plugins.stores.sparqlstore.SPARQLUpdateStore.open:3: WARNING: Unexpected indentation.
/home/cjmarkie/Projects/rdflib/rdflib/plugins/stores/sparqlstore.py:docstring of rdflib.plugins.stores.sparqlstore.SPARQLUpdateStore.open:4: WARNING: Block quote ends without a blank line; unexpected unindent.
/home/cjmarkie/Projects/rdflib/rdflib/plugins/stores/sparqlstore.py:docstring of rdflib.plugins.stores.sparqlstore.SPARQLUpdateStore.triples:12: WARNING: Unexpected indentation.
/home/cjmarkie/Projects/rdflib/rdflib/plugins/stores/sparqlstore.py:docstring of rdflib.plugins.stores.sparqlstore.SPARQLUpdateStore.triples:15: WARNING: Block quote ends without a blank line; unexpected unindent.
/home/cjmarkie/Projects/rdflib/rdflib/plugins/stores/sparqlstore.py:docstring of rdflib.plugins.stores.sparqlstore.SPARQLUpdateStore.triples:17: WARNING: Content block expected for the "warning" directive; none found.
/home/cjmarkie/Projects/rdflib/rdflib/plugins/stores/sparqlstore.py:docstring of rdflib.plugins.stores.sparqlstore.SPARQLUpdateStore.triples:18: WARNING: Explicit markup ends without a blank line; unexpected unindent.
/home/cjmarkie/Projects/rdflib/rdflib/plugins/stores/sparqlstore.py:docstring of rdflib.plugins.stores.sparqlstore.SPARQLUpdateStore.triples:19: WARNING: Bullet list ends without a blank line; unexpected unindent.
/home/cjmarkie/Projects/rdflib/rdflib/plugins/stores/sparqlstore.py:docstring of rdflib.plugins.stores.sparqlstore.SPARQLUpdateStore.triples:28: WARNING: Unexpected indentation.
/home/cjmarkie/Projects/rdflib/rdflib/plugins/stores/sparqlstore.py:docstring of rdflib.plugins.stores.sparqlstore.SPARQLUpdateStore.triples:29: WARNING: Block quote ends without a blank line; unexpected unindent.
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
/home/cjmarkie/Projects/rdflib/docs/_themes/armstrong/layout.html:17: RemovedInSphinx30Warning: To modify script_files in the theme is deprecated. Please insert a <script> tag directly in your theme instead.                                                                                                               
  {%- else %}
writing output... [100%] utilities                                                                                                                                                                                                                                                                                            
/home/cjmarkie/Projects/rdflib/docs/persistence.rst:23: WARNING: undefined label: bsddb (if the link has no caption the label must precede a section header)
/home/cjmarkie/Projects/rdflib/docs/persistence.rst:23: WARNING: undefined label: bsddb3 (if the link has no caption the label must precede a section header)
/home/cjmarkie/Projects/rdflib/docs/utilities.rst:21: WARNING: term not in glossary: functional properties
generating indices...  genindex py-modindexdone
highlighting module code... [100%] rdflib.void                                                                                                                                                                                                                                                                                
writing additional pages...  searchdone
copying images... [100%] _static/ContextHierarchy.png                                                                                                                                                                                                                                                                         
copying static files... ... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 34 warnings.

The HTML pages are in _build/html.

Build finished. The HTML pages are in _build/html.

Replaces #1007.
Closes #938.

[coveralls]

Coverage decreased (-0.08%) to 75.861% when pulling 5f4a2e0 on effigies:improved_docco_style into a22f453 on RDFLib:master.

[white-gecko]

How does it relate to #570?

[nicholascar]

Awesome stuff thanks @effigies! Clearly you're way ahead on the Sphinx workings than I am and I really appreciate your time to improve this ahead of the 5.0.0 release (this weekend!).

I'm happy to approve but I'll leave it to @white-gecko to finalise the PR since he's asked a question.

[effigies]

@white-gecko I did not see #570 and haven't played with epytext, but if that's useful I can add it to this PR.

[white-gecko]

:-)
@nicholascar @effigies I have no clue, what epytext is, I just wanted to ask for your expertise how that pullrequest relates to yours and if we can close the other one as well after merging yours. If epytext is something useful, we should include it.

[effigies]

It looks like in #569 it was determined that there isn't much epytext syntax remaining, so I think #570 can be closed outright.

If we find syntax like that described in http://epydoc.sourceforge.net/fields.html, then we can revisit, but the likely solution would be to replace it to be consistent with the rest of RDFlib, rather than adding a Sphinx extension.

[white-gecko]

Ah ok, so it is like PEP 257, then we should go for PEP 257.