DOC: render qrules transitions with Mermaid

.cspell.json

@@ -43,8 +43,8 @@
     "allclose",
     "ampform",
     "arange",
-    "asdot",
     "aslatex",
+    "asmermaid",
     "atfi",
     "autoupdate",
     "axhline",

.github/workflows/benchmark.yml

@@ -24,7 +24,7 @@ jobs:
       - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.13"
-      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
       - name: Run pytest-benchmark
         run: uvx --from poethepoet poe benchmark
       - name: Warn on performance decrease

.github/workflows/cd.yml

@@ -25,7 +25,7 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - uses: ComPWA/actions/build-pypi-distribution@13f1a3b0c831615fb49c008bcc48113da8a76477 # 4.0.2
-      - uses: pypa/gh-action-pypi-publish@release/v1
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
   push:
     if: startsWith(github.ref, 'refs/tags') && !github.event.release.prerelease
     secrets: inherit

.github/workflows/redirect-gh-pages.yml

@@ -41,4 +41,4 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - id: deployment
-        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1

.pre-commit-config.yaml

@@ -16,7 +16,7 @@ repos:
       - id: check-useless-excludes
 
   - repo: https://github.com/ComPWA/policy
-    rev: 0.9.6
+    rev: 0.9.7
     hooks:
       - id: check-dev-files
 
@@ -60,7 +60,7 @@ repos:
       - id: strip-nb-whitespace
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.16.5
+    rev: v0.16.6
     hooks:
       - id: ruff-check
         args: [--fix]
@@ -96,7 +96,7 @@ repos:
       - id: trailing-whitespace
 
   - repo: https://github.com/tombi-toml/tombi-pre-commit
-    rev: v1.5.0
+    rev: v1.5.4
     hooks:
       - id: tombi-format
       - id: tombi-lint
@@ -121,7 +121,7 @@ repos:
         pass_filenames: false
 
   - repo: https://github.com/streetsidesoftware/cspell-cli
-    rev: v10.1.0
+    rev: v10.2.0
     hooks:
       - id: cspell
 
@@ -137,12 +137,12 @@ repos:
           )$
 
   - repo: https://github.com/astral-sh/ty-pre-commit
-    rev: v0.0.77
+    rev: v0.0.80
     hooks:
       - id: ty
         args: [--group=types, --no-default-groups]
 
   - repo: https://github.com/astral-sh/uv-pre-commit
-    rev: 0.12.8
+    rev: 0.12.12
     hooks:
       - id: uv-lock

docs/_static/mermaid.css

@@ -0,0 +1,13 @@
+/* Render Mermaid diagrams at their natural size instead of stretching them over
+the full page width (see sphinxcontrib/mermaid/default.css.j2). */
+pre.mermaid > svg {
+  height: auto !important;
+  max-width: 100% !important;
+  width: auto !important;
+}
+
+/* Hide graph edges behind labels in Sphinx-rendered Mermaid diagrams. Target
+the outer HTML wrapper so multiline labels have one continuous background. */
+pre.mermaid g.edgeLabel foreignObject > div {
+  background-color: var(--pst-color-on-background) !important;
+}

docs/amplitude-analysis.ipynb

@@ -95,10 +95,10 @@
    },
    "outputs": [],
    "source": [
-    "import graphviz\n",
+    "from IPython.display import Markdown\n",
     "\n",
-    "dot = qrules.io.asdot(reaction, collapse_graphs=True)\n",
-    "graphviz.Source(dot)"
+    "src = qrules.io.asmermaid(reaction, collapse_graphs=True, markdown=True)\n",
+    "Markdown(src)"
    ]
   },
   {
@@ -368,7 +368,11 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "tags": [
+     "remove-output"
+    ]
+   },
    "outputs": [],
    "source": [
     "from tensorwaves.data import TFPhaseSpaceGenerator, TFUniformRealNumberGenerator\n",
@@ -1191,6 +1195,8 @@
    },
    "outputs": [],
    "source": [
+    "import graphviz\n",
+    "\n",
     "dot = sp.dotprint(unfolded_expression.args[0].args[0].args[0].args[0])\n",
     "graphviz.Source(dot)"
    ]
@@ -1652,7 +1658,11 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "tags": [
+     "full-width"
+    ]
+   },
    "outputs": [],
    "source": [
     "covariance_matrix = fit_result.specifics.covariance\n",
@@ -1845,6 +1855,7 @@
     "    bins=bins,\n",
     "    alpha=0.6,\n",
     "    label=[Rf\"${p.latex}$\" for p in sub_intensities],\n",
+    "    rasterized=True,\n",
     "    stacked=True,\n",
     ")\n",
     "\n",
@@ -1908,7 +1919,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.13.13"
+   "version": "3.13.15"
   }
  },
  "nbformat": 4,

docs/amplitude-analysis/analytic-continuation.ipynb

@@ -27,10 +27,9 @@
     "import warnings\n",
     "\n",
     "import ampform\n",
-    "import graphviz\n",
     "import matplotlib.pyplot as plt\n",
     "import qrules\n",
-    "from IPython.display import Math, display\n",
+    "from IPython.display import Markdown, Math\n",
     "\n",
     "from tensorwaves.data import (\n",
     "    SympyDataTransformer,\n",
@@ -62,12 +61,13 @@
     "    allowed_intermediate_particles=[\"a(0)(980)0\", \"a(2)(1320)0\"],\n",
     "    formalism=\"canonical-helicity\",\n",
     ")\n",
-    "dot = qrules.io.asdot(\n",
+    "src = qrules.io.asmermaid(\n",
     "    reaction,\n",
     "    collapse_graphs=True,\n",
     "    render_node=False,\n",
+    "    markdown=True,\n",
     ")\n",
-    "graphviz.Source(dot)"
+    "Markdown(src)"
    ]
   },
   {
@@ -95,15 +95,11 @@
     "k_plus = pdg[\"K+\"]\n",
     "k_minus = pdg[\"K+\"]\n",
     "two_k_mass = round(k_minus.mass + k_plus.mass, 3)\n",
-    "display(\n",
-    "    Math(\n",
-    "        Rf\"m_{{{a_meson.latex}}} = {a_meson.mass} \\pm\"\n",
-    "        Rf\" {a_meson.width}\\;\\mathrm{{GeV}}\"\n",
-    "    ),\n",
-    "    Math(\n",
-    "        Rf\"m_{{{k_plus.latex}}} + m_{{{k_minus.latex}}} =\"\n",
-    "        Rf\" {two_k_mass}\\;\\mathrm{{GeV}}\"\n",
-    "    ),\n",
+    "Math(\n",
+    "    Rf\"\"\"\\begin{{array}}{{c}}\n",
+    "    m_{{{a_meson.latex}}} = {a_meson.mass} \\pm {a_meson.width}\\;\\mathrm{{GeV}} \\\\\n",
+    "    m_{{{k_plus.latex}}} + m_{{{k_minus.latex}}} = {two_k_mass}\\;\\mathrm{{GeV}}\n",
+    "    \\end{{array}}\"\"\"\n",
     ")"
    ]
   },
@@ -236,7 +232,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.13.13"
+   "version": "3.13.15"
   }
  },
  "nbformat": 4,

docs/conf.py

@@ -1,11 +1,7 @@
-from __future__ import annotations
-
 import os
 import subprocess
-import warnings
 
 import requests
-from sphinx.deprecation import RemovedInSphinx10Warning
 from sphinx_api_relink.helpers import (
     get_branch_name,
     get_execution_mode,
@@ -15,8 +11,6 @@
     set_intersphinx_version_remapping,
 )
 
-warnings.filterwarnings("ignore", category=RemovedInSphinx10Warning)
-
 
 def create_tensorflow_inventory() -> None:
     if os.path.exists("tensorflow.inv"):
@@ -75,7 +69,7 @@ def get_tensorflow_url() -> str:
     "tensorwaves.interface.OutputType": "obj",
     "tensorwaves.interface.ParameterValue": "obj",
 }
-author = "Common Partial Wave Analysis"
+author = ""
 autodoc_default_options = {
     "members": True,
     "undoc-members": True,
@@ -126,10 +120,12 @@ def get_tensorflow_url() -> str:
     "sphinx_design",
     "sphinx_thebe",
     "sphinx_togglebutton",
+    "sphinxcontrib.mermaid",
 ]
 generate_apidoc_package_path = f"../src/{PACKAGE}"
 graphviz_output_format = "svg"
 html_copy_source = True  # needed for download notebook button
+html_css_files = ["mermaid.css"]
 html_favicon = "_static/favicon.ico"
 html_last_updated_fmt = "%-d %B %Y"
 html_logo = (
@@ -231,6 +227,16 @@ def get_tensorflow_url() -> str:
     "https://unix.stackexchange.com/a/129144",
 ]
 linkcheck_timeout = 60
+mermaid_height = "auto"  # do not stretch diagrams to the default 500px
+mermaid_init_config = {
+    "flowchart": {
+        "nodeSpacing": 30,
+        "rankSpacing": 40,
+        "useMaxWidth": False,
+    },
+    "startOnLoad": False,
+    "themeVariables": {"fontSize": "12px"},
+}
 modindex_common_prefix = [f"{PACKAGE}."]
 myst_enable_extensions = [
     "amsmath",
@@ -239,6 +245,7 @@ def get_tensorflow_url() -> str:
     "smartquotes",
     "substitution",
 ]
+myst_fence_as_directive = ["mermaid"]
 myst_heading_anchors = 4
 myst_substitutions = {
     "branch": BRANCH,
@@ -255,6 +262,7 @@ def get_tensorflow_url() -> str:
 nb_execution_show_tb = True
 nb_execution_timeout = -1
 nb_output_stderr = "remove"
+nb_render_markdown_format = "myst"
 nitpick_ignore = [
     ("py:class", "tensorflow.keras.losses.Loss"),
     ("py:class", "tensorflow.python.keras.losses.Loss"),

docs/usage.ipynb

@@ -560,16 +560,10 @@
    },
    "outputs": [],
    "source": [
+    "from ampform.io import aslatex\n",
     "from IPython.display import Math\n",
     "\n",
-    "\n",
-    "def display_definitions(definitions):\n",
-    "    for symbol, expr in definitions.items():\n",
-    "        latex = sp.multiline_latex(symbol, expr)\n",
-    "        display(Math(latex))\n",
-    "\n",
-    "\n",
-    "display_definitions(cartesian_to_polar)"
+    "Math(aslatex(cartesian_to_polar))"
    ]
   },
   {
@@ -793,7 +787,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.13.12"
+   "version": "3.13.15"
   }
  },
  "nbformat": 4,

docs/usage/binned-fit.ipynb

@@ -238,6 +238,7 @@
    },
    "outputs": [],
    "source": [
+    "from ampform.io import aslatex\n",
     "from IPython.display import Math\n",
     "\n",
     "substitutions = {\n",
@@ -246,8 +247,7 @@
     "}\n",
     "integral = sp.Integral(expression, (x, 0, 1))\n",
     "evaluated_integral = integral.subs(substitutions).doit()\n",
-    "latex = sp.multiline_latex(integral, evaluated_integral, environment=\"eqnarray\")\n",
-    "Math(latex)"
+    "Math(aslatex({integral: evaluated_integral}))"
    ]
   }
  ],
@@ -270,7 +270,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.13.12"
+   "version": "3.13.15"
   }
  },
  "nbformat": 4,

docs/usage/caching.ipynb

@@ -187,12 +187,10 @@
    },
    "outputs": [],
    "source": [
+    "from ampform.io import aslatex\n",
     "from IPython.display import Math\n",
     "\n",
-    "display(top_expression)\n",
-    "for symbol, expr in sub_expressions.items():\n",
-    "    latex = sp.multiline_latex(symbol, expr, environment=\"eqnarray\")\n",
-    "    display(Math(latex))"
+    "Math(aslatex([top_expression, sub_expressions]))"
    ]
   },
   {
@@ -330,7 +328,11 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "tags": [
+     "full-width"
+    ]
+   },
    "outputs": [],
    "source": [
     "cache_transformer.functions"
@@ -486,7 +488,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.13.13"
+   "version": "3.13.15"
   }
  },
  "nbformat": 4,