docs!: abbreviate annotations in API

.mypy.ini

@@ -28,6 +28,8 @@ ignore_missing_imports = True
 ignore_missing_imports = True
 [mypy-setuptools.*]
 ignore_missing_imports = True
+[mypy-sphinx.*]
+ignore_missing_imports = True
 [mypy-sympy.*]
 ignore_missing_imports = True
 [mypy-tensorflow.*]

docs/_static/linebreaks-api.css

@@ -0,0 +1,6 @@
+/* cspell:ignore paren */
+/* https://github.com/sphinx-doc/sphinx/issues/5868 */
+span.sig-paren ~ em::before {
+  content: "\a        ";
+  white-space: pre;
+}

docs/abbreviate_signature.py

@@ -0,0 +1,72 @@
+"""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.
+"""
+
+# cspell:ignore docutils
+# pylint: disable=import-error
+# pyright: reportMissingImports=false
+import sphinx.domains.python
+from docutils import nodes
+from sphinx import addnodes
+from sphinx.environment import BuildEnvironment
+
+
+def replace_link(text: str) -> str:
+    replacements = {
+        "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",
+        "numpy.typing._array_like._SupportsArray": "numpy.typing.ArrayLike",
+        "numpy.typing._dtype_like._DTypeDict": "numpy.typing.DTypeLike",
+        "numpy.typing._dtype_like._SupportsDType": "numpy.typing.DTypeLike",
+        "typing_extensions.Protocol": "typing.Protocol",
+    }
+    for old, new in replacements.items():
+        if text == old:
+            return new
+    return text
+
+
+def new_type_to_xref(
+    text: str, env: BuildEnvironment = None
+) -> addnodes.pending_xref:
+    """Convert a type string to a cross reference node."""
+    if text == "None":
+        reftype = "obj"
+    else:
+        reftype = "class"
+
+    if env:
+        kwargs = {
+            "py:module": env.ref_context.get("py:module"),
+            "py:class": env.ref_context.get("py:class"),
+        }
+    else:
+        kwargs = {}
+
+    text = replace_link(text)
+    short_text = text.split(".")[-1]
+
+    numpy_types = {
+        "numpy.typing.ArrayLike",
+        "numpy.typing.DTypeLike",
+    }
+    if text in numpy_types:
+        text = "numpy.typing"
+        reftype = "mod"
+
+    return addnodes.pending_xref(
+        "",
+        nodes.Text(short_text),
+        refdomain="py",
+        reftype=reftype,
+        reftarget=text,
+        **kwargs,
+    )
+
+
+sphinx.domains.python.type_to_xref = new_type_to_xref  # noqa: F811

docs/conf.py

@@ -25,7 +25,10 @@
     __release = get_distribution(package).version
     version = ".".join(__release.split(".")[:3])
 
-# -- Generate API skeleton ----------------------------------------------------
+# -- Generate API ------------------------------------------------------------
+sys.path.insert(0, os.path.abspath("."))
+import abbreviate_signature
+
 shutil.rmtree("api", ignore_errors=True)
 subprocess.call(
     " ".join(
@@ -94,12 +97,18 @@
         ]
     ),
 }
+autodoc_insert_signature_linebreaks = False
+graphviz_output_format = "svg"
 html_copy_source = True  # needed for download notebook button
+html_css_files = []
+if autodoc_insert_signature_linebreaks:
+    html_css_files.append("linebreaks-api.css")
 html_favicon = "_static/favicon.ico"
 html_show_copyright = False
 html_show_sourcelink = False
 html_show_sphinx = False
 html_sourcelink_suffix = ""
+html_static_path = ["_static"]
 html_theme = "sphinx_book_theme"
 html_theme_options = {
     "repository_url": f"https://github.com/ComPWA/{repo_name}",