docs: automatically link code examples to API (#147)

* build: install jupyterlab-myst * build: install sphinx-codeautolink * chore: rename to abbreviate_signature script to _relink_references.py * ci: update pip constraints and pre-commit config * ci: use black --preview flag * docs: activate sphinx_codeautolink extension * fix: use correct syntax for myst refs * style: format with black 22.1.0 style Co-authored-by: GitHub <[email protected]> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
ComPWA · Jan 30, 2022 · 8379238 · 8379238
1 parent 7b11b19
commit 8379238
Show file tree

Hide file tree

Showing 19 changed files with 131 additions and 54 deletions.
diff --git a/.constraints/py3.10.txt b/.constraints/py3.10.txt
@@ -15,12 +15,12 @@ attrs==21.4.0
 babel==2.9.1
 backcall==0.2.0
 beautifulsoup4==4.10.0
-black==21.12b0
+black==22.1.0
 bleach==4.1.0
 certifi==2021.10.8
 cffi==1.15.0
 cfgv==3.3.1
-charset-normalizer==2.0.10
+charset-normalizer==2.0.11
 click==8.0.3
 colorama==0.4.4
 coverage==6.3
@@ -45,7 +45,6 @@ flake8-pytest-style==1.6.0
 flake8-rst-docstrings==0.2.5
 flake8-type-ignore==0.1.0.post2 ; python_version >= "3.8.0"
 flake8-use-fstring==1.3
-fuzzywuzzy==0.18.0
 gitdb==4.0.9
 gitpython==3.1.26
 gprof2dot==2021.2.21
@@ -76,6 +75,8 @@ jupyter-server-mathjax==0.2.3
 jupyter-sphinx==0.3.2
 jupyterlab==3.2.8
 jupyterlab-code-formatter==1.4.10
+jupyterlab-markup==1.0.1
+jupyterlab-myst==0.1.6 ; python_version >= "3.7.0"
 jupyterlab-pygments==0.1.2
 jupyterlab-server==2.10.3
 jupyterlab-widgets==1.0.2
@@ -155,6 +156,7 @@ soupsieve==2.3.1
 sphinx==4.4.0
 sphinx-autobuild==2021.3.14
 sphinx-book-theme==0.2.0
+sphinx-codeautolink==0.10.0
 sphinx-copybutton==0.4.0
 sphinx-panels==0.6.0
 sphinx-thebe==0.0.10
@@ -167,13 +169,13 @@ sphinxcontrib-htmlhelp==2.0.0
 sphinxcontrib-jsmath==1.0.1
 sphinxcontrib-qthelp==1.0.3
 sphinxcontrib-serializinghtml==1.1.5
-sphobjinv==2.1
+sphobjinv==2.2
 sqlalchemy==1.4.31
 stack-data==0.1.4
 terminado==0.13.1
 testpath==0.5.0
 toml==0.10.2
-tomli==1.2.3
+tomli==2.0.0
 tornado==6.1
 tox==3.24.5
 tqdm==4.62.3
@@ -182,7 +184,7 @@ types-docutils==0.17.4
 types-pkg-resources==0.1.3
 types-pyyaml==6.0.3
 types-requests==2.27.7
-types-setuptools==57.4.7
+types-setuptools==57.4.8
 types-urllib3==1.26.7
 typing-extensions==4.0.1
 urllib3==1.26.8

diff --git a/.constraints/py3.6.txt b/.constraints/py3.6.txt
@@ -15,12 +15,12 @@ attrs==21.4.0
 babel==2.9.1
 backcall==0.2.0
 beautifulsoup4==4.10.0
-black==21.12b0
+black==22.1.0
 bleach==4.1.0
 certifi==2021.10.8
 cffi==1.15.0
 cfgv==3.3.1
-charset-normalizer==2.0.10
+charset-normalizer==2.0.11
 click==8.0.3
 colorama==0.4.4
 contextvars==2.4
@@ -44,7 +44,6 @@ flake8-polyfill==1.0.2
 flake8-pytest-style==1.6.0
 flake8-rst-docstrings==0.2.5
 flake8-use-fstring==1.3
-fuzzywuzzy==0.18.0
 gitdb==4.0.9
 gitpython==3.1.18
 gprof2dot==2021.2.21
@@ -154,6 +153,7 @@ soupsieve==2.3.1
 sphinx==4.3.2 ; python_version < "3.8.0"
 sphinx-autobuild==2021.3.14
 sphinx-book-theme==0.2.0
+sphinx-codeautolink==0.10.0
 sphinx-copybutton==0.4.0
 sphinx-panels==0.6.0
 sphinx-thebe==0.0.10
@@ -166,7 +166,7 @@ sphinxcontrib-htmlhelp==2.0.0
 sphinxcontrib-jsmath==1.0.1
 sphinxcontrib-qthelp==1.0.3
 sphinxcontrib-serializinghtml==1.1.5
-sphobjinv==2.1
+sphobjinv==2.2
 sqlalchemy==1.4.31
 terminado==0.12.1
 testpath==0.5.0
@@ -181,7 +181,7 @@ types-docutils==0.17.4
 types-pkg-resources==0.1.3
 types-pyyaml==6.0.3
 types-requests==2.27.7
-types-setuptools==57.4.7
+types-setuptools==57.4.8
 types-urllib3==1.26.7
 typing-extensions==4.0.1 ; python_version < "3.8.0"
 urllib3==1.26.8

diff --git a/.constraints/py3.7.txt b/.constraints/py3.7.txt
@@ -14,12 +14,12 @@ attrs==21.4.0
 babel==2.9.1
 backcall==0.2.0
 beautifulsoup4==4.10.0
-black==21.12b0
+black==22.1.0
 bleach==4.1.0
 certifi==2021.10.8
 cffi==1.15.0
 cfgv==3.3.1
-charset-normalizer==2.0.10
+charset-normalizer==2.0.11
 click==8.0.3
 colorama==0.4.4
 coverage==6.3
@@ -42,7 +42,6 @@ flake8-polyfill==1.0.2
 flake8-pytest-style==1.6.0
 flake8-rst-docstrings==0.2.5
 flake8-use-fstring==1.3
-fuzzywuzzy==0.18.0
 gitdb==4.0.9
 gitpython==3.1.26
 gprof2dot==2021.2.21
@@ -74,6 +73,8 @@ jupyter-server-mathjax==0.2.3
 jupyter-sphinx==0.3.2
 jupyterlab==3.2.8
 jupyterlab-code-formatter==1.4.10
+jupyterlab-markup==1.0.1
+jupyterlab-myst==0.1.6 ; python_version >= "3.7.0"
 jupyterlab-pygments==0.1.2
 jupyterlab-server==2.10.3
 jupyterlab-widgets==1.0.2
@@ -152,6 +153,7 @@ soupsieve==2.3.1
 sphinx==4.3.2 ; python_version < "3.8.0"
 sphinx-autobuild==2021.3.14
 sphinx-book-theme==0.2.0
+sphinx-codeautolink==0.10.0
 sphinx-copybutton==0.4.0
 sphinx-panels==0.6.0
 sphinx-thebe==0.0.10
@@ -164,12 +166,12 @@ sphinxcontrib-htmlhelp==2.0.0
 sphinxcontrib-jsmath==1.0.1
 sphinxcontrib-qthelp==1.0.3
 sphinxcontrib-serializinghtml==1.1.5
-sphobjinv==2.1
+sphobjinv==2.2
 sqlalchemy==1.4.31
 terminado==0.13.1
 testpath==0.5.0
 toml==0.10.2
-tomli==1.2.3
+tomli==2.0.0
 tornado==6.1
 tox==3.24.5
 tqdm==4.62.3
@@ -179,7 +181,7 @@ types-docutils==0.17.4
 types-pkg-resources==0.1.3
 types-pyyaml==6.0.3
 types-requests==2.27.7
-types-setuptools==57.4.7
+types-setuptools==57.4.8
 types-urllib3==1.26.7
 typing-extensions==4.0.1 ; python_version < "3.8.0"
 urllib3==1.26.8

diff --git a/.constraints/py3.8.txt b/.constraints/py3.8.txt
@@ -15,12 +15,12 @@ attrs==21.4.0
 babel==2.9.1
 backcall==0.2.0
 beautifulsoup4==4.10.0
-black==21.12b0
+black==22.1.0
 bleach==4.1.0
 certifi==2021.10.8
 cffi==1.15.0
 cfgv==3.3.1
-charset-normalizer==2.0.10
+charset-normalizer==2.0.11
 click==8.0.3
 colorama==0.4.4
 coverage==6.3
@@ -45,7 +45,6 @@ flake8-pytest-style==1.6.0
 flake8-rst-docstrings==0.2.5
 flake8-type-ignore==0.1.0.post2 ; python_version >= "3.8.0"
 flake8-use-fstring==1.3
-fuzzywuzzy==0.18.0
 gitdb==4.0.9
 gitpython==3.1.26
 gprof2dot==2021.2.21
@@ -77,6 +76,8 @@ jupyter-server-mathjax==0.2.3
 jupyter-sphinx==0.3.2
 jupyterlab==3.2.8
 jupyterlab-code-formatter==1.4.10
+jupyterlab-markup==1.0.1
+jupyterlab-myst==0.1.6 ; python_version >= "3.7.0"
 jupyterlab-pygments==0.1.2
 jupyterlab-server==2.10.3
 jupyterlab-widgets==1.0.2
@@ -156,6 +157,7 @@ soupsieve==2.3.1
 sphinx==4.4.0
 sphinx-autobuild==2021.3.14
 sphinx-book-theme==0.2.0
+sphinx-codeautolink==0.10.0
 sphinx-copybutton==0.4.0
 sphinx-panels==0.6.0
 sphinx-thebe==0.0.10
@@ -168,13 +170,13 @@ sphinxcontrib-htmlhelp==2.0.0
 sphinxcontrib-jsmath==1.0.1
 sphinxcontrib-qthelp==1.0.3
 sphinxcontrib-serializinghtml==1.1.5
-sphobjinv==2.1
+sphobjinv==2.2
 sqlalchemy==1.4.31
 stack-data==0.1.4
 terminado==0.13.1
 testpath==0.5.0
 toml==0.10.2
-tomli==1.2.3
+tomli==2.0.0
 tornado==6.1
 tox==3.24.5
 tqdm==4.62.3
@@ -183,7 +185,7 @@ types-docutils==0.17.4
 types-pkg-resources==0.1.3
 types-pyyaml==6.0.3
 types-requests==2.27.7
-types-setuptools==57.4.7
+types-setuptools==57.4.8
 types-urllib3==1.26.7
 typing-extensions==4.0.1
 urllib3==1.26.8

diff --git a/.constraints/py3.9.txt b/.constraints/py3.9.txt
@@ -15,12 +15,12 @@ attrs==21.4.0
 babel==2.9.1
 backcall==0.2.0
 beautifulsoup4==4.10.0
-black==21.12b0
+black==22.1.0
 bleach==4.1.0
 certifi==2021.10.8
 cffi==1.15.0
 cfgv==3.3.1
-charset-normalizer==2.0.10
+charset-normalizer==2.0.11
 click==8.0.3
 colorama==0.4.4
 coverage==6.3
@@ -45,7 +45,6 @@ flake8-pytest-style==1.6.0
 flake8-rst-docstrings==0.2.5
 flake8-type-ignore==0.1.0.post2 ; python_version >= "3.8.0"
 flake8-use-fstring==1.3
-fuzzywuzzy==0.18.0
 gitdb==4.0.9
 gitpython==3.1.26
 gprof2dot==2021.2.21
@@ -76,6 +75,8 @@ jupyter-server-mathjax==0.2.3
 jupyter-sphinx==0.3.2
 jupyterlab==3.2.8
 jupyterlab-code-formatter==1.4.10
+jupyterlab-markup==1.0.1
+jupyterlab-myst==0.1.6 ; python_version >= "3.7.0"
 jupyterlab-pygments==0.1.2
 jupyterlab-server==2.10.3
 jupyterlab-widgets==1.0.2
@@ -155,6 +156,7 @@ soupsieve==2.3.1
 sphinx==4.4.0
 sphinx-autobuild==2021.3.14
 sphinx-book-theme==0.2.0
+sphinx-codeautolink==0.10.0
 sphinx-copybutton==0.4.0
 sphinx-panels==0.6.0
 sphinx-thebe==0.0.10
@@ -167,13 +169,13 @@ sphinxcontrib-htmlhelp==2.0.0
 sphinxcontrib-jsmath==1.0.1
 sphinxcontrib-qthelp==1.0.3
 sphinxcontrib-serializinghtml==1.1.5
-sphobjinv==2.1
+sphobjinv==2.2
 sqlalchemy==1.4.31
 stack-data==0.1.4
 terminado==0.13.1
 testpath==0.5.0
 toml==0.10.2
-tomli==1.2.3
+tomli==2.0.0
 tornado==6.1
 tox==3.24.5
 tqdm==4.62.3
@@ -182,7 +184,7 @@ types-docutils==0.17.4
 types-pkg-resources==0.1.3
 types-pyyaml==6.0.3
 types-requests==2.27.7
-types-setuptools==57.4.7
+types-setuptools==57.4.8
 types-urllib3==1.26.7
 typing-extensions==4.0.1
 urllib3==1.26.8

diff --git a/.cspell.json b/.cspell.json
@@ -128,6 +128,7 @@
         "colab",
         "commitlint",
         "compwa",
+        "concat",
         "conds",
         "displaystyle",
         "doctest",

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -41,7 +41,7 @@ repos:
       - id: trailing-whitespace
 
   - repo: https://github.com/ComPWA/repo-maintenance
-    rev: 0.0.99
+    rev: 0.0.101
     hooks:
       - id: check-dev-files
         args:
@@ -55,12 +55,12 @@ repos:
       - id: format-setup-cfg
 
   - repo: https://github.com/psf/black
-    rev: 21.12b0
+    rev: 22.1.0
     hooks:
       - id: black
 
   - repo: https://github.com/asottile/blacken-docs
-    rev: v1.12.0
+    rev: v1.12.1
     hooks:
       - id: blacken-docs
 
@@ -101,6 +101,8 @@ repos:
     rev: 1.2.3
     hooks:
       - id: nbqa-black
+        additional_dependencies:
+          - black>=22.1.0
       - id: nbqa-flake8
       - id: nbqa-isort