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 #1878

Author: aucampia

.github/workflows/validate.yaml

@@ -25,15 +25,18 @@ jobs:
           - python-version: "3.7"
             os: ubuntu-latest
             extensive-tests: true
+            TOXENV_SUFFIX: "-docs"
           - python-version: "3.8"
             os: ubuntu-latest
             TOX_EXTRA_COMMAND: "- isort --check-only --diff ."
+            TOXENV_SUFFIX: "-docs"
           - python-version: "3.9"
             os: ubuntu-latest
             TOX_EXTRA_COMMAND: "- black --check --diff ./rdflib"
           - python-version: "3.10"
             os: ubuntu-latest
             TOX_EXTRA_COMMAND: "flake8 --exit-zero rdflib"
+            TOXENV_SUFFIX: "-docs"
     steps:
       - uses: actions/checkout@v3
       - name: Set up Python ${{ matrix.python-version }}
@@ -72,6 +75,7 @@ jobs:
             OS=${{ matrix.os }} \
             EXTENSIVE=${{ matrix.extensive-tests }} \
             TOX_PYTHON_VERSION=${{ matrix.python-version }} \
+            TOXENV_SUFFIX=${{ matrix.TOXENV_SUFFIX }} \
             gha:validate
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.readthedocs.yaml

@@ -12,7 +12,9 @@ formats:
 build:
   os: ubuntu-20.04
   tools:
-    python: "3.7"
+    # Using 3.9 as earlier versions have trouble generating documentation for
+    # `@typing.overload`` with type aliases.
+    python: "3.9"
 
 python:
   install:

CHANGELOG.md

@@ -58,6 +58,22 @@ and will be removed for release.
 <!-- -->
 <!-- -->
 
+- Fixed some cross-referencing issues in RDFLib documentation.
+  Closed [issue #1878](https://github.com/RDFLib/rdflib/issues/1878).
+  [PR #2036](https://github.com/RDFLib/rdflib/pull/2036).
+
+<!-- -->
+<!-- -->
+<!-- CHANGE BARRIER: END -->
+<!-- -->
+<!-- -->
+
+<!-- -->
+<!-- -->
+<!-- CHANGE BARRIER: START -->
+<!-- -->
+<!-- -->
+
 - PLACEHOLDER.
   Description of changes.
   Closed [issue #....](https://github.com/RDFLib/rdflib/issues/).

Taskfile.yml

@@ -95,7 +95,7 @@ tasks:
           -m tox \
           {{.CLI_ARGS}}
     env:
-      TOXENV: '{{if .TOX_PYTHON_VERSION}}py{{mustRegexReplaceAll "^([0-9]+)[.]([0-9]+).*" .TOX_PYTHON_VERSION "${1}${2}"}}{{if .EXTENSIVE}}-extensive{{end}}{{end}}'
+      TOXENV: '{{if .TOX_PYTHON_VERSION}}py{{mustRegexReplaceAll "^([0-9]+)[.]([0-9]+).*" .TOX_PYTHON_VERSION "${1}${2}"}}{{if .EXTENSIVE}}-extensive{{end}}{{.TOXENV_SUFFIX | default ""}}{{end}}'
   test:
     desc: Run tests
     cmds:

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:

docs/conf.py

@@ -254,3 +254,42 @@ def find_version(filename):
     #  "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"),
+        ]
+    )

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.

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
     

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)?
 

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`