docs: abbreviate annotations in API

.constraints/py3.6.txt

@@ -6,7 +6,7 @@
 #
 absl-py==0.12.0
 alabaster==0.7.12
-ampform==0.8.0
+ampform==0.8.1
 anyio==2.2.0
 apipkg==1.5
 appdirs==1.4.4
@@ -16,10 +16,10 @@ astroid==2.5.6
 astunparse==1.6.3
 async-generator==1.10
 attrs==20.3.0
-babel==2.9.0
+babel==2.9.1
 backcall==0.2.0
 beautifulsoup4==4.9.3
-black==21.4b1
+black==21.4b2
 bleach==3.3.0
 cachetools==4.2.2
 certifi==2020.12.5
@@ -49,7 +49,7 @@ flake8-comprehensions==3.4.0
 flake8-plugin-utils==1.3.1
 flake8-polyfill==1.0.2
 flake8-pytest-style==1.4.1
-flake8-rst-docstrings==0.2.1
+flake8-rst-docstrings==0.2.2
 flake8-use-fstring==1.1
 flake8==3.9.1
 flatbuffers==1.12
@@ -68,7 +68,7 @@ hepunits==2.1.0
 identify==2.2.4
 idna==2.10
 imagesize==1.2.0
-iminuit==2.4.0
+iminuit==2.5.0
 immutables==0.15
 importlib-metadata==4.0.1
 importlib-resources==3.0.0
@@ -168,8 +168,8 @@ python-dateutil==2.8.1
 pytz==2021.1
 pyyaml==5.4.1
 pyzmq==22.0.3
-qrules==0.8.0
-qtconsole==5.0.3
+qrules==0.8.1
+qtconsole==5.1.0
 qtpy==1.9.0
 regex==2021.4.4
 requests-oauthlib==1.3.0

.constraints/py3.7.txt

@@ -6,7 +6,7 @@
 #
 absl-py==0.12.0
 alabaster==0.7.12
-ampform==0.8.0
+ampform==0.8.1
 anyio==2.2.0
 apipkg==1.5
 appdirs==1.4.4
@@ -16,10 +16,10 @@ astroid==2.5.6
 astunparse==1.6.3
 async-generator==1.10
 attrs==20.3.0
-babel==2.9.0
+babel==2.9.1
 backcall==0.2.0
 beautifulsoup4==4.9.3
-black==21.4b1
+black==21.4b2
 bleach==3.3.0
 cachetools==4.2.2
 certifi==2020.12.5
@@ -47,7 +47,7 @@ flake8-comprehensions==3.4.0
 flake8-plugin-utils==1.3.1
 flake8-polyfill==1.0.2
 flake8-pytest-style==1.4.1
-flake8-rst-docstrings==0.2.1
+flake8-rst-docstrings==0.2.2
 flake8-use-fstring==1.1
 flake8==3.9.1
 flatbuffers==1.12
@@ -66,12 +66,12 @@ hepunits==2.1.0
 identify==2.2.4
 idna==2.10
 imagesize==1.2.0
-iminuit==2.4.0
+iminuit==2.5.0
 importlib-metadata==4.0.1
 iniconfig==1.1.1
 ipykernel==5.5.3
 ipython-genutils==0.2.0
-ipython==7.22.0
+ipython==7.23.0
 ipywidgets==7.6.3
 isort==5.8.0
 jax==0.2.12
@@ -101,6 +101,7 @@ llvmlite==0.36.0
 markdown-it-py==0.6.2
 markdown==3.3.4
 markupsafe==1.1.1
+matplotlib-inline==0.1.2
 matplotlib==3.4.1
 mccabe==0.6.1
 mdit-py-plugins==0.2.6
@@ -164,8 +165,8 @@ python-dateutil==2.8.1
 pytz==2021.1
 pyyaml==5.4.1
 pyzmq==22.0.3
-qrules==0.8.0
-qtconsole==5.0.3
+qrules==0.8.1
+qtconsole==5.1.0
 qtpy==1.9.0
 regex==2021.4.4
 requests-oauthlib==1.3.0

.constraints/py3.8.txt

@@ -6,7 +6,7 @@
 #
 absl-py==0.12.0
 alabaster==0.7.12
-ampform==0.8.0
+ampform==0.8.1
 anyio==2.2.0
 apipkg==1.5
 appdirs==1.4.4
@@ -16,10 +16,10 @@ astroid==2.5.6
 astunparse==1.6.3
 async-generator==1.10
 attrs==20.3.0
-babel==2.9.0
+babel==2.9.1
 backcall==0.2.0
 beautifulsoup4==4.9.3
-black==21.4b1
+black==21.4b2
 bleach==3.3.0
 cachetools==4.2.2
 certifi==2020.12.5
@@ -47,7 +47,7 @@ flake8-comprehensions==3.4.0
 flake8-plugin-utils==1.3.1
 flake8-polyfill==1.0.2
 flake8-pytest-style==1.4.1
-flake8-rst-docstrings==0.2.1
+flake8-rst-docstrings==0.2.2
 flake8-use-fstring==1.1
 flake8==3.9.1
 flatbuffers==1.12
@@ -66,12 +66,12 @@ hepunits==2.1.0
 identify==2.2.4
 idna==2.10
 imagesize==1.2.0
-iminuit==2.4.0
+iminuit==2.5.0
 importlib-metadata==4.0.1
 iniconfig==1.1.1
 ipykernel==5.5.3
 ipython-genutils==0.2.0
-ipython==7.22.0
+ipython==7.23.0
 ipywidgets==7.6.3
 isort==5.8.0
 jax==0.2.12
@@ -101,6 +101,7 @@ llvmlite==0.36.0
 markdown-it-py==0.6.2
 markdown==3.3.4
 markupsafe==1.1.1
+matplotlib-inline==0.1.2
 matplotlib==3.4.1
 mccabe==0.6.1
 mdit-py-plugins==0.2.6
@@ -164,8 +165,8 @@ python-dateutil==2.8.1
 pytz==2021.1
 pyyaml==5.4.1
 pyzmq==22.0.3
-qrules==0.8.0
-qtconsole==5.0.3
+qrules==0.8.1
+qtconsole==5.1.0
 qtpy==1.9.0
 regex==2021.4.4
 requests-oauthlib==1.3.0

.github/workflows/requirements-cron.yml

@@ -73,10 +73,10 @@ jobs:
       - name: Create Pull Request
         uses: peter-evans/create-pull-request@v3
         with:
-          commit-message: "ci: upgrade developer dependencies"
+          commit-message: "ci: upgrade pinned requirements (automatic)"
           committer: GitHub <noreply@github.com>
           author: GitHub <noreply@github.com>
-          title: "ci: upgrade developer dependencies"
+          title: "ci: upgrade pinned requirements"
           labels: |
             🖱️ DX
           branch-suffix: timestamp

.github/workflows/requirements-pr.yml

@@ -74,7 +74,7 @@ jobs:
           git checkout -b ${GITHUB_HEAD_REF}
           if [[ $(git status -s) ]]; then
             git add -A
-            git commit -m "ci: upgrade developer dependencies (automatic)"
+            git commit -m "ci: upgrade pinned requirements (automatic)"
             git config pull.rebase true
             git pull origin ${GITHUB_HEAD_REF}
             git push origin HEAD:${GITHUB_HEAD_REF}

.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.*]

.pre-commit-config.yaml

@@ -63,7 +63,7 @@ repos:
       - id: markdownlint
 
   - repo: https://github.com/nbQA-dev/nbQA
-    rev: 0.7.0
+    rev: 0.8.0
     hooks:
       - id: nbqa-black
         args: [--nbqa-mutate]
@@ -84,7 +84,7 @@ repos:
         language_version: 12.18.2 # prettier does not specify node correctly
 
   - repo: https://github.com/ComPWA/mirrors-pyright
-    rev: v1.1.135
+    rev: v1.1.136
     hooks:
       - id: pyright
 

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