docs: switch to sphinx-autodoc-typehints

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"],