docs: automatically link code examples to API

.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
 commonmark==0.9.1
@@ -78,6 +78,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
@@ -164,6 +166,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
@@ -182,15 +185,15 @@ sympy==1.9
 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
 traitlets==5.1.1
 types-docutils==0.17.4
 types-pkg-resources==0.1.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

.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
 commonmark==0.9.1
@@ -162,6 +162,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
@@ -188,7 +189,7 @@ typed-ast==1.5.2
 types-docutils==0.17.4
 types-pkg-resources==0.1.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

.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
 commonmark==0.9.1
@@ -76,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
@@ -161,6 +163,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
@@ -178,7 +181,7 @@ sympy==1.9
 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
@@ -187,7 +190,7 @@ typed-ast==1.5.2
 types-docutils==0.17.4
 types-pkg-resources==0.1.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

.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
 commonmark==0.9.1
@@ -79,6 +79,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
@@ -165,6 +167,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
@@ -183,15 +186,15 @@ sympy==1.9
 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
 traitlets==5.1.1
 types-docutils==0.17.4
 types-pkg-resources==0.1.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

.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
 commonmark==0.9.1
@@ -78,6 +78,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
@@ -164,6 +166,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
@@ -182,15 +185,15 @@ sympy==1.9
 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
 traitlets==5.1.1
 types-docutils==0.17.4
 types-pkg-resources==0.1.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

.cspell.json

@@ -143,6 +143,7 @@
         "colorbar",
         "commitlint",
         "compwa",
+        "concat",
         "conds",
         "coolwarm",
         "displaystyle",

.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
       - id: nbqa-pyupgrade

docs/_extend_docstrings.py

@@ -99,7 +99,7 @@ def extend_ComplexSqrt() -> None:
     expr = ComplexSqrt(x)
     _append_to_docstring(
         ComplexSqrt,
-        fR"""
+        Rf"""
     .. math:: {sp.latex(expr)} = {sp.latex(expr.evaluate())}
         :label: ComplexSqrt
     """,
@@ -409,7 +409,7 @@ def extend_relativistic_breit_wigner_with_ff() -> None:
     )
     _append_to_docstring(
         relativistic_breit_wigner_with_ff,
-        fR"""
+        Rf"""
     The general form of a relativistic Breit-Wigner with Blatt-Weisskopf form
     factor is:
 

docs/conf.py

@@ -118,6 +118,7 @@ def fetch_logo(url: str, output_path: str) -> None:
     "sphinx.ext.mathjax",
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
+    "sphinx_codeautolink",
     "sphinx_copybutton",
     "sphinx_panels",
     "sphinx_thebe",
@@ -166,6 +167,7 @@ def fetch_logo(url: str, output_path: str) -> None:
     "Slider": "symplot.Slider",
 }
 autodoc_typehints_format = "short"
+codeautolink_concat_default = True
 AUTODOC_INSERT_SIGNATURE_LINEBREAKS = False
 graphviz_output_format = "svg"
 html_copy_source = True  # needed for download notebook button

docs/usage/amplitude.ipynb

@@ -49,6 +49,14 @@
     "%pip install -q ampform[doc,viz] IPython"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "```{autolink-concat}\n",
+    "```"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -874,7 +882,7 @@
     "    plotted_intensity,\n",
     "    (m, 2 * pi0.mass, 2.5),\n",
     "    axis_center=(2 * pi0.mass, 0),\n",
-    "    xlabel=fR\"$m(\\pi^{0}\\pi^{0})$\",\n",
+    "    xlabel=Rf\"$m(\\pi^{0}\\pi^{0})$\",\n",
     "    ylabel=\"$I$\",\n",
     "    backend=\"matplotlib\",\n",
     ");"

docs/usage/dynamics.ipynb

@@ -49,6 +49,14 @@
     "%pip install -q ampform[doc,viz] IPython"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "```{autolink-concat}\n",
+    "```"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {
@@ -162,9 +170,9 @@
     "from ampform.dynamics import BreakupMomentumSquared\n",
     "\n",
     "m, m_a, m_b, d = sp.symbols(\"m, m_a, m_b, d\")\n",
-    "s = m ** 2\n",
+    "s = m**2\n",
     "q_squared = BreakupMomentumSquared(s, m_a, m_b)\n",
-    "ff2 = BlattWeisskopfSquared(L, z=q_squared * d ** 2)"
+    "ff2 = BlattWeisskopfSquared(L, z=q_squared * d**2)"
    ]
   },
   {
@@ -316,7 +324,7 @@
     "from ampform.dynamics import relativistic_breit_wigner\n",
     "\n",
     "m, m0, w0 = sp.symbols(\"m, m0, Gamma0\")\n",
-    "rel_bw = relativistic_breit_wigner(s=m ** 2, mass0=m0, gamma0=w0)\n",
+    "rel_bw = relativistic_breit_wigner(s=m**2, mass0=m0, gamma0=w0)\n",
     "rel_bw"
    ]
   },

docs/usage/dynamics/analytic-continuation.ipynb

@@ -49,6 +49,14 @@
     "%pip install -q ampform[doc,viz] IPython"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "```{autolink-concat}\n",
+    "```"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -288,14 +296,14 @@
     "from ampform.dynamics import ComplexSqrt\n",
     "\n",
     "m = sp.Symbol(\"m\", real=True)\n",
-    "rho_c = PhaseSpaceFactorComplex(m ** 2, m_a, m_b)\n",
-    "rho_ac = PhaseSpaceFactorAnalytic(m ** 2, m_a, m_b)\n",
+    "rho_c = PhaseSpaceFactorComplex(m**2, m_a, m_b)\n",
+    "rho_ac = PhaseSpaceFactorAnalytic(m**2, m_a, m_b)\n",
     "np_rho_c, sliders = symplot.prepare_sliders(\n",
     "    plot_symbol=m, expression=rho_c.doit()\n",
     ")\n",
     "np_rho_ac = sp.lambdify((m, m_a, m_b), rho_ac.doit())\n",
     "np_breakup_momentum = sp.lambdify(\n",
-    "    (m, m_a, m_b), ComplexSqrt(q_squared.subs(s, m ** 2).doit())\n",
+    "    (m, m_a, m_b), ComplexSqrt(q_squared.subs(s, m**2).doit())\n",
     ")"
    ]
   },