docs: fix sphinx nitpicky issues (#2036)

Enable nitpicky mode for Sphinx and fix all warnings and errors
that occur when running with nitpicky enabled.

Other changes:
- Add a tox environment for building docs (-docs). This is so we can
  test building docs on various versions of python as there seems to be
  some differences in warnings between different versions. This tox
  environment is enabled for linux CI builds.
- Change readthedocs to use python 3.9 as earlier versions do not handle
  `@typing.overload` with type aliases.
- Fixes https://github.com/RDFLib/rdflib/issues/1878

11 files changed, 84 insertions, 46 deletions

diff --git a/docs/apidocs/examples.rst b/docs/apidocs/examples.rst
index 22175473..4e3908b5 100644
--- a/docs/apidocs/examples.rst
+++ b/docs/apidocs/examples.rst
@@ -3,112 +3,112 @@ examples Package
 
 These examples all live in ``./examples`` in the source-distribution of RDFLib.
 
-:mod:`conjunctive_graphs` Module
---------------------------------
+:mod:`~examples.conjunctive_graphs` Module
+------------------------------------------
 
 .. automodule:: examples.conjunctive_graphs
     :members:
     :undoc-members:
     :show-inheritance:
 
-:mod:`custom_datatype` Module
------------------------------
+:mod:`~examples.custom_datatype` Module
+---------------------------------------
 
 .. automodule:: examples.custom_datatype
     :members:
     :undoc-members:
     :show-inheritance:
 
-:mod:`custom_eval` Module
--------------------------
+:mod:`~examples.custom_eval` Module
+-----------------------------------
 
 .. automodule:: examples.custom_eval
     :members:
     :undoc-members:
     :show-inheritance:
 
-:mod:`foafpaths` Module
------------------------
+:mod:`~examples.foafpaths` Module
+---------------------------------
 
 .. automodule:: examples.foafpaths
     :members:
     :undoc-members:
     :show-inheritance:
 
-:mod:`prepared_query` Module
-----------------------------
+:mod:`~examples.prepared_query` Module
+--------------------------------------
 
 .. automodule:: examples.prepared_query
     :members:
     :undoc-members:
     :show-inheritance:
 
-:mod:`resource_example` Module
-------------------------------
+:mod:`~examples.resource_example` Module
+----------------------------------------
 
 .. automodule:: examples.resource_example
     :members:
     :undoc-members:
     :show-inheritance:
 
-:mod:`berkeleydb_example` Module
---------------------------------
+:mod:`~examples.berkeleydb_example` Module
+------------------------------------------
 
 .. automodule:: examples.berkeleydb_example
     :members:
     :undoc-members:
     :show-inheritance:
 
-:mod:`slice` Module
--------------------
+:mod:`~examples.slice` Module
+-----------------------------
 
 .. automodule:: examples.slice
     :members:
     :undoc-members:
     :show-inheritance:
 
-:mod:`smushing` Module
-----------------------
+:mod:`~examples.smushing` Module
+--------------------------------
 
 .. automodule:: examples.smushing
     :members:
     :undoc-members:
     :show-inheritance:
 
-:mod:`sparql_query_example` Module
-----------------------------------
+:mod:`~examples.sparql_query_example` Module
+--------------------------------------------
 
 .. automodule:: examples.sparql_query_example
     :members:
     :undoc-members:
     :show-inheritance:
 
-:mod:`sparql_update_example` Module
------------------------------------
+:mod:`~examples.sparql_update_example` Module
+---------------------------------------------
 
 .. automodule:: examples.sparql_update_example
     :members:
     :undoc-members:
     :show-inheritance:
 
-:mod:`sparqlstore_example` Module
------------------------------------
+:mod:`~examples.sparqlstore_example` Module
+-------------------------------------------
 
 .. automodule:: examples.sparqlstore_example
     :members:
     :undoc-members:
     :show-inheritance:
 
-:mod:`swap_primer` Module
--------------------------
+:mod:`~examples.swap_primer` Module
+-----------------------------------
 
 .. automodule:: examples.swap_primer
     :members:
     :undoc-members:
     :show-inheritance:
 
-:mod:`transitive` Module
-------------------------
+:mod:`~examples.transitive` Module
+----------------------------------
 
 .. automodule:: examples.transitive
     :members:
diff --git a/docs/conf.py b/docs/conf.py
index 52476621..044a175f 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -254,3 +254,42 @@ suppress_warnings = [
     #  "WARNING: more than one target found for cross-reference"
     "ref.python",
 ]
+
+nitpicky = True
+
+nitpick_ignore = [
+    ("py:data", "typing.Literal"),
+    ("py:class", "typing.IO[bytes]"),
+    ("py:class", "http.client.HTTPMessage"),
+    ("py:class", "importlib.metadata.EntryPoint"),
+    ("py:class", "xml.dom.minidom.Document"),
+    ("py:class", "xml.dom.minidom.DocumentFragment"),
+    # sphinx-autodoc-typehints has some issues with TypeVars.
+    # https://github.com/tox-dev/sphinx-autodoc-typehints/issues/39
+    ("py:class", "rdflib.plugin.PluginT"),
+    # These are related to pyparsing.
+    ("py:class", "Diagnostics"),
+    ("py:class", "ParseAction"),
+    ("py:class", "ParseFailAction"),
+    ("py:class", "pyparsing.core.TokenConverter"),
+    ("py:class", "pyparsing.results.ParseResults"),
+]
+
+if sys.version_info < (3, 9):
+    nitpick_ignore.extend(
+        [
+            ("py:class", "_TriplePatternType"),
+            ("py:class", "_TripleType"),
+            ("py:class", "_ObjectType"),
+            ("py:class", "_PredicateType"),
+            ("py:class", "_SubjectType"),
+            ("py:class", "TextIO"),
+        ]
+    )
+
+if sys.version_info < (3, 8):
+    nitpick_ignore.extend(
+        [
+            ("py:class", "importlib_metadata.EntryPoint"),
+        ]
+    )
diff --git a/docs/developers.rst b/docs/developers.rst
index 25ead436..c6ac6763 100644
--- a/docs/developers.rst
+++ b/docs/developers.rst
@@ -132,7 +132,7 @@ ideally be updated to the pytest test-style when they are touched.
 Test should go into the ``test/`` directory, either into an existing test file
 with a name that is applicable to the test being written, or into a new test
 file with a name that is descriptive of the tests placed in it. Test files
-should be named `test_*.py` so that `pytest can discover them
+should be named ``test_*.py`` so that `pytest can discover them
 <https://docs.pytest.org/en/latest/explanation/goodpractices.html#conventions-for-python-test-discovery>`_.
 
 Running static checks
@@ -399,6 +399,6 @@ No matter how you create the release tag, remember to upload tarball to pypi wit
   # WARNING: once uploaded can never be modified, only deleted!
   twine upload dist/rdflib-X.X.X[.-]*
 
-Set new dev version number in the above locations, i.e. next release `-dev`: ``5.0.1-dev`` and commit again.
+Set new dev version number in the above locations, i.e. next release ``-dev``: ``5.0.1-dev`` and commit again.
 
 Tweet, email mailing list and inform members in the chat.
diff --git a/docs/namespaces_and_bindings.rst b/docs/namespaces_and_bindings.rst
index c8a76fec..cac84680 100644
--- a/docs/namespaces_and_bindings.rst
+++ b/docs/namespaces_and_bindings.rst
@@ -29,7 +29,7 @@ namespaces provided grows with user contributions to RDFLib.
 
 These Namespaces, and any others that users define, can also be associated with prefixes using the :class:`rdflib.namespace.NamespaceManager`, e.g. using ``foaf`` for ``http://xmlns.com/foaf/0.1/``.
 
-Each RDFLib graph has a :attr:`~rdflib.graph.Graph.namespace_manager` that keeps a list of namespace to prefix mappings. The namespace manager is populated when reading in RDF, and these prefixes are used when serialising RDF, or when parsing SPARQL queries. Prefixes can be bound with the :meth:`rdflib.graph.bind` method::
+Each RDFLib graph has a :attr:`~rdflib.graph.Graph.namespace_manager` that keeps a list of namespace to prefix mappings. The namespace manager is populated when reading in RDF, and these prefixes are used when serialising RDF, or when parsing SPARQL queries. Prefixes can be bound with the :meth:`rdflib.graph.Graph.bind` method::
 
     from rdflib import Graph, Namespace
     from rdflib.namespace import FOAF
@@ -41,15 +41,15 @@ Each RDFLib graph has a :attr:`~rdflib.graph.Graph.namespace_manager` that keeps
     g.bind("ex", EX)      # bind a user-declared namespace to a prefix
     
 
-The :meth:`rdflib.graph.bind` method is actually supplied by the :class:`rdflib.namespace.NamespaceManager` class - see next.
+The :meth:`rdflib.graph.Graph.bind` method is actually supplied by the :class:`rdflib.namespace.NamespaceManager` class - see next.
 
 NamespaceManager
 ----------------
 
-Each RDFLib graph comes with a :class:`rdflib.namespace.NamespaceManager` instance in the `namespace_manager` field; you can use the `bind` method of this instance to bind a prefix to a namespace URI,
-as above, however note that the `NamespaceManager` automatically performs some bindings according to a selected strategy. 
+Each RDFLib graph comes with a :class:`rdflib.namespace.NamespaceManager` instance in the :attr:`~rdflib.graph.Graph.namespace_manager` field; you can use the :meth:`~rdflib.namespace.NamespaceManager.bind` method of this instance to bind a prefix to a namespace URI,
+as above, however note that the :class:`~rdflib.namespace.NamespaceManager` automatically performs some bindings according to a selected strategy. 
 
-Namespace binding strategies are indicated with the `bind_namespaces` input parameter to `NamespaceManager` instances 
+Namespace binding strategies are indicated with the ``bind_namespaces`` input parameter to :class:`~rdflib.namespace.NamespaceManager` instances 
 and may be set via ``Graph`` also::
 
     from rdflib import Graph
@@ -95,7 +95,7 @@ for example::
     
     
 
-`NamespaceManager` also has a method to normalize a given url::
+:class:`~rdflib.namespace.NamespaceManager` also has a method to normalize a given url::
 
     from rdflib.namespace import NamespaceManager
     
diff --git a/docs/persisting_n3_terms.rst b/docs/persisting_n3_terms.rst
index 820f307f..1138b4c3 100644
--- a/docs/persisting_n3_terms.rst
+++ b/docs/persisting_n3_terms.rst
@@ -77,7 +77,7 @@ A formula-aware store could also support the persistence of this distinction by
 
 This function would return all the Blank Node identifiers assigned to formulae or just those that contain statements matching the given triple pattern and would be the way a serializer determines if a term refers to a formula (in order to properly serializer it).
 
-How much would such an interface reduce the need to model formulae terms as first class objects (perhaps to be returned by the :meth:`~rdflib.Graph.triple` function)? Would it be more useful for the :class:`~rdflib.Graph` (or the store itself) to return a Context object in place of a formula term (using the formulae interface to make this determination)?
+How much would such an interface reduce the need to model formulae terms as first class objects (perhaps to be returned by the :meth:`~rdflib.Graph.triples` function)? Would it be more useful for the :class:`~rdflib.Graph` (or the store itself) to return a Context object in place of a formula term (using the formulae interface to make this determination)?
 
 Conversely, would these interfaces (variables and formulae) be considered optimizations only since you have the distinction by the kinds of terms triples returns (which would be expanded to include variables and formulae)?
 
diff --git a/docs/plugin_parsers.rst b/docs/plugin_parsers.rst
index ed351c0c..f199b922 100644
--- a/docs/plugin_parsers.rst
+++ b/docs/plugin_parsers.rst
@@ -22,7 +22,6 @@ Name      Class
 ========= ====================================================================
 json-ld   :class:`~rdflib.plugins.parsers.jsonld.JsonLDParser`
 hext      :class:`~rdflib.plugins.parsers.hext.HextuplesParser`
-html      :class:`~rdflib.plugins.parsers.structureddata.StructuredDataParser`
 n3        :class:`~rdflib.plugins.parsers.notation3.N3Parser`
 nquads    :class:`~rdflib.plugins.parsers.nquads.NQuadsParser`
 nt        :class:`~rdflib.plugins.parsers.ntriples.NTParser`
diff --git a/docs/plugin_query_results.rst b/docs/plugin_query_results.rst
index fb2ffb94..f44c2768 100644
--- a/docs/plugin_query_results.rst
+++ b/docs/plugin_query_results.rst
@@ -4,7 +4,7 @@
 Plugin query results
 ====================
 
-Plugins for reading and writing of (SPARQL) :class:`~rdflib.query.QueryResult` - pass ``name`` to either :meth:`~rdflib.query.QueryResult.parse` or :meth:`~rdflib.query.QueryResult.serialize` 
+Plugins for reading and writing of (SPARQL) :class:`~rdflib.query.Result` - pass ``name`` to either :meth:`~rdflib.query.Result.parse` or :meth:`~rdflib.query.Result.serialize` 
 
 
 Parsers
diff --git a/docs/plugin_serializers.rst b/docs/plugin_serializers.rst
index 249b0aed..ac836ee7 100644
--- a/docs/plugin_serializers.rst
+++ b/docs/plugin_serializers.rst
@@ -25,7 +25,7 @@ pretty-xml :class:`~rdflib.plugins.serializers.rdfxml.PrettyXMLSerializer`
 trig       :class:`~rdflib.plugins.serializers.trig.TrigSerializer`
 trix       :class:`~rdflib.plugins.serializers.trix.TriXSerializer`
 turtle     :class:`~rdflib.plugins.serializers.turtle.TurtleSerializer`
-longturtle :class:`~rdflib.plugins.serializers.turtle.LongTurtleSerializer`
+longturtle :class:`~rdflib.plugins.serializers.longturtle.LongTurtleSerializer`
 xml        :class:`~rdflib.plugins.serializers.rdfxml.XMLSerializer`
 ========== ===============================================================
 
diff --git a/docs/rdf_terms.rst b/docs/rdf_terms.rst
index b00d34ff..0ca431a4 100644
--- a/docs/rdf_terms.rst
+++ b/docs/rdf_terms.rst
@@ -191,7 +191,7 @@ A literal in an RDF graph contains one or two named components.
     
 All literals have a lexical form being a Unicode string, which SHOULD be in Normal Form C.
     
-Plain literals have a lexical form and optionally a language tag as defined by :rfc:`3066`, normalized to lowercase. An exception will be raised if illegal language-tags are passed to :meth:`rdflib.term.Literal.__init__`.
+Plain literals have a lexical form and optionally a language tag as defined by :rfc:`3066`, normalized to lowercase. An exception will be raised if illegal language-tags are passed to :meth:`rdflib.term.Literal.__new__`.
     
 Typed literals have a lexical form and a datatype URI being an RDF URI reference.
     
diff --git a/docs/upgrade4to5.rst b/docs/upgrade4to5.rst
index 8916ab35..1859ff1a 100644
--- a/docs/upgrade4to5.rst
+++ b/docs/upgrade4to5.rst
@@ -76,9 +76,9 @@ General Bugs Fixed:
   `PR #663 <https://github.com/RDFLib/rdflib/pull/663>`_
 * namespace.py fix compute_qname missing namespaces
   `PR #649 <https://github.com/RDFLib/rdflib/pull/649>`_
-* RDFa parsing Error! `__init__()` got an unexpected keyword argument 'encoding'
+* RDFa parsing Error! ``__init__()`` got an unexpected keyword argument 'encoding'
   `ISSUE #639 <https://github.com/RDFLib/rdflib/issues/639>`_
-* Bugfix: `term.Literal.__add__`
+* Bugfix: ``term.Literal.__add__``
   `PR #451 <https://github.com/RDFLib/rdflib/pull/451>`_
 * fixup of #443
   `PR #445 <https://github.com/RDFLib/rdflib/pull/445>`_
@@ -204,7 +204,7 @@ Documentation Fixes:
   `PR #712 <https://github.com/RDFLib/rdflib/pull/712>`_
 * make doctest support py2/py3
   `ISSUE #707 <https://github.com/RDFLib/rdflib/issues/707>`_
-* `pip install rdflib` (as per README.md) gets OSError on Mint 18.1
+* ``pip install rdflib`` (as per README.md) gets OSError on Mint 18.1
   `ISSUE #704 <https://github.com/RDFLib/rdflib/issues/704>`_
   `PR #717 <https://github.com/RDFLib/rdflib/pull/717>`_
 * Use <<= instead of deprecated << in SPARQL parser
@@ -261,6 +261,6 @@ Documentation Fixes:
   `PR #712 <https://github.com/RDFLib/rdflib/pull/712>`_
 * make doctest support py2/py3
   `ISSUE #707 <https://github.com/RDFLib/rdflib/issues/707>`_
-* `pip install rdflib` (as per README.md) gets OSError on Mint 18.1
+* ``pip install rdflib`` (as per README.md) gets OSError on Mint 18.1
   `ISSUE #704 <https://github.com/RDFLib/rdflib/issues/704>`_
 
diff --git a/docs/utilities.rst b/docs/utilities.rst
index 849c5598..381f9070 100644
--- a/docs/utilities.rst
+++ b/docs/utilities.rst
@@ -55,7 +55,7 @@ RDFLib graphs override ``__getitem__`` and we pervert the slice triple
 to be a RDF triple instead. This lets slice syntax be a shortcut for
 :meth:`~rdflib.graph.Graph.triples`,
 :meth:`~rdflib.graph.Graph.subject_predicates`,
-:meth:`~rdflib.graph.Graph.contains`, and other Graph query-methods:
+:meth:`~rdflib.graph.Graph.__contains__`, and other Graph query-methods:
 
 .. code-block:: python