docs: suport type aliases in API

See ComPWA/ampform#207

docs/_relink_references.py

@@ -0,0 +1,111 @@
+# pylint: disable=import-error, import-outside-toplevel
+# pyright: reportMissingImports=false
+"""Abbreviated the annotations generated by sphinx-autodoc.
+
+It's not necessary to generate the full path of type hints, because they are
+rendered as clickable links.
+
+See also https://github.com/sphinx-doc/sphinx/issues/5868.
+"""
+
+from typing import List
+
+import sphinx.domains.python
+from docutils import nodes
+from sphinx.addnodes import pending_xref
+from sphinx.environment import BuildEnvironment
+
+__TARGET_SUBSTITUTIONS = {
+    "HelicityAdapter": "ampform.kinematics.HelicityAdapter",
+    "ParameterValue": "tensorwaves.interface.ParameterValue",
+    "a set-like object providing a view on D's items": "typing.ItemsView",
+    "a set-like object providing a view on D's keys": "typing.KeysView",
+    "an object providing a view on D's values": "typing.ValuesView",
+    "sp.Expr": "sympy.core.expr.Expr",
+    "sp.Symbol": "sympy.core.symbol.Symbol",
+}
+__REF_TYPE_SUBSTITUTIONS = {
+    "None": "obj",
+    "tensorwaves.interface.InputType": "obj",
+    "tensorwaves.interface.OutputType": "obj",
+    "tensorwaves.interface.ParameterValue": "obj",
+}
+
+
+try:  # Sphinx >=4.4.0
+    # https://github.com/sphinx-doc/sphinx/blob/v4.4.0/sphinx/domains/python.py#L110-L133
+    from sphinx.addnodes import pending_xref_condition
+    from sphinx.domains.python import parse_reftarget
+
+    def _new_type_to_xref(
+        target: str,
+        env: BuildEnvironment = None,
+        suppress_prefix: bool = False,
+    ) -> pending_xref:
+        """Convert a type string to a cross reference node."""
+        reftype, target, title, refspecific = parse_reftarget(
+            target, suppress_prefix
+        )
+        target = __TARGET_SUBSTITUTIONS.get(target, target)
+        reftype = __REF_TYPE_SUBSTITUTIONS.get(target, reftype)
+
+        assert env is not None
+        return pending_xref(
+            "",
+            *__create_nodes(env, title),
+            refdomain="py",
+            reftype=reftype,
+            reftarget=target,
+            refspecific=refspecific,
+            **__get_env_kwargs(env),
+        )
+
+except ImportError:  # Sphinx <4.4.0
+    # https://github.com/sphinx-doc/sphinx/blob/v4.3.2/sphinx/domains/python.py#L83-L107
+    def _new_type_to_xref(
+        target: str,
+        env: BuildEnvironment = None,
+        suppress_prefix: bool = False,
+    ) -> pending_xref:
+        # pylint: disable=unused-argument
+        """Convert a type string to a cross reference node."""
+        if target == "None":
+            reftype = "obj"
+        else:
+            reftype = "class"
+
+        target = __TARGET_SUBSTITUTIONS.get(target, target)
+        reftype = __REF_TYPE_SUBSTITUTIONS.get(target, reftype)
+
+        assert env is not None
+        return pending_xref(
+            "",
+            *__create_nodes(env, target),
+            refdomain="py",
+            reftype=reftype,
+            reftarget=target,
+            **__get_env_kwargs(env),
+        )
+
+
+def __get_env_kwargs(env: BuildEnvironment) -> dict:
+    if env:
+        return {
+            "py:module": env.ref_context.get("py:module"),
+            "py:class": env.ref_context.get("py:class"),
+        }
+    return {}
+
+
+def __create_nodes(env: BuildEnvironment, title: str) -> List[nodes.Node]:
+    short_name = title.split(".")[-1]
+    if env.config.python_use_unqualified_type_names:
+        return [
+            pending_xref_condition("", short_name, condition="resolved"),
+            pending_xref_condition("", title, condition="*"),
+        ]
+    return [nodes.Text(short_name)]
+
+
+def relink_references() -> None:
+    sphinx.domains.python.type_to_xref = _new_type_to_xref

docs/conf.py

@@ -55,9 +55,9 @@ def fetch_logo(url: str, output_path: str) -> None:
 
 # -- Generate API ------------------------------------------------------------
 sys.path.insert(0, os.path.abspath("."))
-from abbreviate_signature import abbreviate_signature  # noqa: E402
+from _relink_references import relink_references  # noqa: E402
 
-abbreviate_signature()
+relink_references()
 shutil.rmtree("api", ignore_errors=True)
 subprocess.call(
     " ".join(
@@ -129,6 +129,11 @@ def fetch_logo(url: str, output_path: str) -> None:
     ),
 }
 autodoc_member_order = "bysource"
+autodoc_type_aliases = {
+    "InputType": "tensorwaves.interface.InputType",
+    "OutputType": "tensorwaves.interface.OutputType",
+    "ParameterValue": "tensorwaves.interface.ParameterValue",
+}
 AUTODOC_INSERT_SIGNATURE_LINEBREAKS = False
 graphviz_output_format = "svg"
 html_copy_source = True  # needed for download notebook button