docs: switch to sphinx-autodoc-typehints

Currently rdflib is relying on sphinx-autodoc's built in handling for type
hints, this however has some deficiencies as it does not handle stuff
inside `if TYPE_CHECKING:` and thus only work in cases where there are no
potential for circular dependencies.

This patch changes sphinx to use sphinx-autodoc-typehints instead, the
documentation generated by this plugin looks slightly different but as a
positive it correctly works with things defined inside `if TYPE_CHECKING:`
guards.

Also:
- moved the `_NamespaceSetString` type alias to `rdflib._type_checking`
  This is so that `sphinx-autodoc-typehints` recognizes it up, as it
  does not handle type aliases that are defined inside
  `if TYPE_CHECKING:` guards in imported files.
- remove sphinx requirements from requirements.dev.txt and
  replaced it with -r docs/sphinx-requirements.txt to reduce redundancy.

Author: aucampia

docs/conf.py

@@ -30,6 +30,7 @@
     "sphinxcontrib.apidoc",
     "sphinx.ext.autodoc",
     #'sphinx.ext.autosummary',
+    "sphinx_autodoc_typehints",
     "sphinx.ext.doctest",
     "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
@@ -42,8 +43,12 @@
 
 apidoc_module_dir = "../rdflib"
 apidoc_output_dir = "apidocs"
+
+# https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html
 autodoc_default_options = {"special-members": True}
-autodoc_typehints = "both"
+
+# https://github.com/tox-dev/sphinx-autodoc-typehints
+always_document_param_types = True
 
 autosummary_generate = True
 

docs/sphinx-requirements.txt

@@ -3,3 +3,4 @@ myst-parser
 sphinx<5
 sphinxcontrib-apidoc
 sphinxcontrib-kroki
+sphinx-autodoc-typehints

rdflib/_type_checking.py

@@ -0,0 +1,29 @@
+"""
+This module contains type aliases that should only be used when type checking
+as it would otherwise introduce a runtime dependency on `typing_extensions` for
+older python versions which is not desirable.
+
+This was made mainly to accommodate ``sphinx-autodoc-typehints`` which cannot
+recognize type aliases from imported files if the type aliases are defined
+inside ``if TYPE_CHECKING:``. So instead of placing the type aliases in normal
+modules inside ``TYPE_CHECKING`` guards they are in this file which should only
+be imported inside ``TYPE_CHECKING`` guards.
+
+.. important::
+    Things inside this module are not for use outside of RDFLib
+    and this module is not part the the RDFLib public API.
+"""
+
+import sys
+
+__all__ = [
+    "_NamespaceSetString",
+]
+
+
+if sys.version_info >= (3, 8):
+    from typing import Literal as PyLiteral
+else:
+    from typing_extensions import Literal as PyLiteral
+
+_NamespaceSetString = PyLiteral["core", "rdflib", "none"]

rdflib/graph.py

@@ -40,7 +40,7 @@
 assert Namespace  # avoid warning
 
 if TYPE_CHECKING:
-    from rdflib.namespace import _NamespaceSetString
+    from rdflib._type_checking import _NamespaceSetString
 
 logger = logging.getLogger(__name__)
 

rdflib/namespace/__init__.py

@@ -344,12 +344,7 @@ def _ipython_key_completions_(self) -> List[str]:
 XMLNS = Namespace("http://www.w3.org/XML/1998/namespace")
 
 if TYPE_CHECKING:
-    if sys.version_info >= (3, 8):
-        from typing import Literal as PyLiteral
-    else:
-        from typing_extensions import Literal as PyLiteral
-
-    _NamespaceSetString = PyLiteral["core", "rdflib", "none"]
+    from rdflib._type_checking import _NamespaceSetString
 
 
 class NamespaceManager(object):

requirements.dev.txt

@@ -6,11 +6,8 @@ flake8-black
 html5lib
 isort
 mypy
-myst-parser
 pytest
 pytest-cov
 pytest-subtests
-sphinx<5
-sphinxcontrib-apidoc
-sphinxcontrib-kroki
 types-setuptools
+-r docs/sphinx-requirements.txt

setup.cfg

@@ -9,6 +9,8 @@ exclude = host,extras,transform,rdfs,pyRdfa,sparql,results,pyMicrodata
 [coverage:run]
 branch = True
 source = rdflib
+omit =
+    */_type_checking.py
 
 [coverage:report]
 # Regexes for lines to exclude from consideration

setup.py

@@ -27,6 +27,7 @@
         "sphinx < 5",
         "sphinxcontrib-apidoc",
         "sphinxcontrib-kroki",
+        "sphinx-autodoc-typehints",
     ],
     "berkeleydb": ["berkeleydb"],
     "networkx": ["networkx"],