Skip to content

DOC: visualize qrules results with Mermaid - #510

Merged
redeboer merged 34 commits into
mainfrom
dependabot/lock-2514a98571
Sep 4, 2026
Merged

DOC: visualize qrules results with Mermaid#510
redeboer merged 34 commits into
mainfrom
dependabot/lock-2514a98571

Conversation

@dependabot

@dependabot dependabot Bot commented on behalf of github Sep 2, 2026

Copy link
Copy Markdown
Contributor

📝 Documentation

  • Decay topologies and transition graphs are rendered with Mermaid instead of Graphviz, both in the notebooks (qrules.io.asmermaid()) and in the docstrings generated by docs/_extend_docstrings.py (.. mermaid:: directives instead of pre-rendered SVGs). The two topologies in get_boost_chain_suffix() are now stacked vertically, so its docstring refers to the top and bottom topology instead of the left and right one.
  • The hand-written Graphviz diagrams for the scattering and production process in {doc}/dynamics/k-matrix are replaced with hand-drawn Feynman diagrams (docs/_static/kmatrix-*.svg), with LaTeX labels and an only-dark variant each, so they follow the theme of the page.
  • {doc}/dynamics/custom shows the source of ResonanceDynamicsBuilder and create_relativistic_breit_wigner() as a folded, syntax-highlighted code block instead of raw print() output, and the amplitude expressions in {doc}/amplitude/formalism are rendered with aslatex(), so symbol and expression appear as one aligned equation. The formalism comparison table in that same notebook is built as Markdown instead of a rich table, which drops rich from the notebooks dependency group.
  • QRules' progress bar no longer appears in the notebook output: each notebook sets the qrules.transition logger to ERROR. Cells that were tagged remove-output only to hide that bar now show their output again.
  • Folded cells that produce a Mermaid diagram carry a code_prompt_show label describing the diagram, and the documentation footer no longer shows an author line (author = "").

🖱️ Developer experience

  • Graphviz is no longer a system dependency for building the documentation: it is dropped from .binder/apt.txt, from ci.yml, from the Read the Docs pixi global install, and from tool.compwa.policy.doc-apt-packages. The public ampform[viz] extra is untouched.
  • sphinxcontrib-mermaid is added to the doc dependency group and myst_fence_as_directive is enabled, so ```mermaid fences render as diagrams. mermaid_height="auto" plus `docs/_static/mermaid.css` draw diagrams at their natural size instead of stretching them to 500px and give edge labels an opaque background, and `mermaid_init_config` tightens node and rank spacing. The `notebooks` group now requires `qrules >=0.10.12` and no longer pulls in `ampform[viz]`.
  • The cSpell allow-list is pruned of entries that no longer occur anywhere in the repository, and *.svg files are excluded from spell checking.

🐛 Bug fixes

  • Equations that used eqnarray ({doc}/dynamics/k-matrix) or align ({doc}/amplitude/formalism) now use aligned. MathJax 4 refuses to nest these AMS structures inside the split that Sphinx wraps math blocks in and inside the $\displaystyle ... $ from IPython.display.Math, so they rendered as Erroneous nesting of equation structures. For the same reason, the amplitude colors are applied with \textcolor instead of the unscoped \color. Closes Equations with eqnarray and align render as an error under MathJax 4 #511
  • html_static_path is restored in the Sphinx configuration and html_css_files points at the existing linebreaks-api.css instead of a non-existent custom.css, so the custom stylesheets are actually copied and loaded.
  • The documentation build no longer performs an HTTP request to determine the scipy intersphinx URL: _get_scipy_url() is dropped in favor of a fixed inventory URL (see Restore the pinned SciPy intersphinx inventory #512), which keeps sphinx-build working offline.

Squash commit messages

* DOC: hide QRules progress bar in notebooks
* DOC: remove author from documentation footer
* DOC: render amplitude expressions with aslatex()
* DOC: render dynamics builder sources as code block
* DOC: render formalism comparison table as Markdown
* DOC: replace K-matrix Graphviz graphs with Feynman diagrams
* DOC: stack topology graphs in get_boost_chain_suffix()
* DX: remove Graphviz as documentation build dependency
* FIX: keep documentation build working offline
* FIX: restore html_static_path in Sphinx config
* FIX: use aligned to avoid MathJax 4 nesting errors
* MAINT: remove obsolete cSpell allow-list entries

Bumps the lock group with 1 update: [astral-sh/setup-uv](https://github.com/astral-sh/setup-uv).


Updates `astral-sh/setup-uv` from 7.6.0 to 10.0.1
- [Release notes](https://github.com/astral-sh/setup-uv/releases)
- [Commits](astral-sh/setup-uv@37802ad...20cfd1b)

---
updated-dependencies:
- dependency-name: astral-sh/setup-uv
  dependency-version: 10.0.1
  dependency-type: direct:production
  update-type: version-update:semver-major
  dependency-group: lock
...

Signed-off-by: dependabot[bot] <support@github.com>
@dependabot dependabot Bot added the ⬆️ Lock This PR upgrades the lock files label Sep 2, 2026
@redeboer redeboer changed the title MAINT: bump astral-sh/setup-uv from 7.6.0 to 10.0.1 in the lock group DOC: visualize qrules results with Mermaid Sep 2, 2026
@redeboer redeboer added this to the 0.16.1 milestone Sep 2, 2026
@redeboer redeboer added 📝 Docs Improvements or additions to documentation 🐛 Bug Something isn't working 🖱️ DX Improvements to the Developer Experience labels Sep 2, 2026
@redeboer
redeboer self-requested a review September 2, 2026 20:14
@redeboer redeboer removed the 🖱️ DX Improvements to the Developer Experience label Sep 3, 2026
@redeboer
redeboer force-pushed the dependabot/lock-2514a98571 branch from 24b5af3 to 43294a6 Compare September 4, 2026 12:38
@redeboer redeboer added the 🖱️ DX Improvements to the Developer Experience label Sep 4, 2026
@redeboer
redeboer merged commit bc92774 into main Sep 4, 2026
36 checks passed
@redeboer
redeboer deleted the dependabot/lock-2514a98571 branch September 4, 2026 14:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

🐛 Bug Something isn't working 📝 Docs Improvements or additions to documentation 🖱️ DX Improvements to the Developer Experience ⬆️ Lock This PR upgrades the lock files

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Render decay graphs with Mermaid instead of Graphviz Equations with eqnarray and align render as an error under MathJax 4

2 participants