flying-sheep · Oct 27, 2026 · Oct 23, 2026 · Oct 23, 2026 · Oct 23, 2026 · Oct 23, 2026
diff --git a/.github/workflows/sync.yaml b/.github/workflows/sync.yaml
@@ -8,6 +8,7 @@ on:
     paths:
       - src/scverse_doc/theme/scverse/static/styles/_tokens.css
       - src/scverse_doc/theme/scverse/static/scverse-fa.svg
+      - src/scverse_doc/static/mathmlfixes.css
       - scripts/**
 
 permissions:
@@ -26,5 +27,10 @@ jobs:
           repository: scverse/scverse.github.io
           path: .upstream/website
           persist-credentials: false
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          repository: tmke8/math-core
+          path: .upstream/math-core
+          persist-credentials: false
       - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
-      - run: uv run scripts/sync_brand_tokens.py --website .upstream/website --check
+      - run: uv run scripts/sync_upstream.py --website .upstream/website --math-core .upstream/math-core --check
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -10,6 +10,16 @@ and this project adheres to [Semantic Versioning][].
 
 ## [Unreleased]
 
+### Changed
+
+- Sphinx 9.1 or newer is required
+
+### Added
+
+- `scverse_doc.math_core` renders math to MathML at build time via [math-core](https://github.com/tmke8/math-core) instead of MathJax (#75)
+  - `math_core_options` configures the converter, e.g. with macros
+  - math-core’s `mathmlfixes.css` is included, fixing e.g. `\boxed` and `\cancel` in Chromium
+
 ### Fixed
 
 - rapids-singlecell’s accents are synced from the website (#78)

diff --git a/biome.jsonc b/biome.jsonc
@@ -7,6 +7,7 @@
             "**",
             "!src/scverse_doc/registry.json",
             "!src/scverse_doc/_accents.json",
+            "!src/scverse_doc/static/mathmlfixes.css",
             "!src/scverse_doc/theme/scverse/static/styles/_tokens.css",
         ],
     },

diff --git a/docs/api.md b/docs/api.md
@@ -9,15 +9,16 @@
 ```{toctree}
 :hidden:
 
-api/config.md
+api/config.rst
 api/theme.md
 api/source.md
-api/registry.md
-api/autodoc.md
-api/napoleon.md
-api/release_notes.md
-api/typed_fields.md
-api/xref_overrides.md
+api/registry.rst
+api/autodoc.rst
+api/napoleon.rst
+api/math_core.rst
+api/release_notes.rst
+api/typed_fields.rst
+api/xref_overrides.rst
 ```
 
 ## {doc}`api/config`
@@ -61,6 +62,10 @@ and private bases left out of `:show-inheritance:`.
 
 Prose `Returns` sections in NumPy-style docstrings.
 
+## {doc}`api/math_core`
+
+Math rendered to MathML at build time, via [math-core](https://github.com/tmke8/math-core) – no JavaScript needed.
+
 ## {doc}`api/release_notes`
 
 A `release-notes` directive, rendering a directory of per-version files grouped by minor version.

diff --git a/docs/api/autodoc.md b/docs/api/autodoc.md
diff --git a/docs/api/autodoc.rst b/docs/api/autodoc.rst
@@ -0,0 +1,4 @@
+``scverse_doc.autodoc``
+=======================
+
+.. automodule:: scverse_doc.autodoc
diff --git a/docs/api/config.md → docs/api/config.rst b/docs/api/config.md → docs/api/config.rst
@@ -1,11 +1,10 @@
-# `scverse_doc.config`
+``scverse_doc.config``
+======================
 
-```{eval-rst}
 .. automodule:: scverse_doc.config
 
 .. autodata:: EXTENSIONS
 
 .. autodata:: MYST_ENABLE_EXTENSIONS
 
 .. autodata:: DEFAULTS
-```
diff --git a/docs/api/math_core.rst b/docs/api/math_core.rst
@@ -0,0 +1,23 @@
+``scverse_doc.math_core``
+=========================
+
+.. automodule:: scverse_doc.math_core
+
+Configuration
+-------------
+
+..  confval:: math_core_options
+    :type: dict
+    :default: ``{}``
+
+    Keyword arguments for math-core’s |LatexToMathML|_, e.g. macros
+    (named without the backslash, arguments as ``#1`` etc.):
+
+    ..  code-block:: python
+
+        math_core_options = dict(
+            macros={"R": r"\mathbb{R}", "vec": r"\mathbf{#1}"},
+        )
+
+.. |LatexToMathML| replace:: ``LatexToMathML``
+.. _LatexToMathML: https://github.com/tmke8/math-core/tree/main/crates/math-core-python#latextomathml
diff --git a/docs/api/napoleon.md b/docs/api/napoleon.md
diff --git a/docs/api/napoleon.rst b/docs/api/napoleon.rst
@@ -0,0 +1,4 @@
+``scverse_doc.napoleon``
+========================
+
+.. automodule:: scverse_doc.napoleon
diff --git a/docs/api/registry.md → docs/api/registry.rst b/docs/api/registry.md → docs/api/registry.rst
@@ -1,6 +1,6 @@
-# `scverse_doc.registry`
+``scverse_doc.registry``
+========================
 
-```{eval-rst}
 .. automodule:: scverse_doc.registry
 
 .. autodata:: packages
@@ -11,4 +11,3 @@
 
 .. autoclass:: Package
     :members:
-```
diff --git a/docs/api/release_notes.md → docs/api/release_notes.rst b/docs/api/release_notes.md → docs/api/release_notes.rst
@@ -1,6 +1,5 @@
-# `scverse_doc.release_notes`
+``scverse_doc.release_notes``
+=============================
 
-```{eval-rst}
 .. automodule:: scverse_doc.release_notes
    :members: FULL_VERSION_RE
-```
diff --git a/docs/api/typed_fields.md b/docs/api/typed_fields.md
diff --git a/docs/api/typed_fields.rst b/docs/api/typed_fields.rst
@@ -0,0 +1,4 @@
+``scverse_doc.typed_fields``
+============================
+
+.. automodule:: scverse_doc.typed_fields
diff --git a/docs/api/xref_overrides.md → docs/api/xref_overrides.rst b/docs/api/xref_overrides.md → docs/api/xref_overrides.rst
@@ -1,6 +1,5 @@
-# `scverse_doc.xref_overrides`
+``scverse_doc.xref_overrides``
+==============================
 
-```{eval-rst}
 .. automodule:: scverse_doc.xref_overrides
    :members: DEFAULT_OVERRIDES
-```
diff --git a/docs/conf.py b/docs/conf.py
@@ -2,7 +2,12 @@
 """Sphinx docs configuration."""
 
 project = "scverse-doc"
-extensions = ["scverse_doc", "sphinxcontrib.bibtex", "sphinx.ext.linkcode"]
+extensions = [
+    "scverse_doc",
+    "sphinxcontrib.bibtex",
+    "sphinx.ext.linkcode",
+    "sphinx_toolbox.rest_example",
+]
 html_logo = "_static/scverse.svg"
 html_theme_options = {"announcement": ""}
 source_repository = "https://github.com/scverse/scverse-doc"

diff --git a/pyproject.toml b/pyproject.toml
@@ -25,7 +25,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dynamic = [ "readme", "version" ]
-dependencies = [ "packaging", "sphinx>=8.1" ]
+dependencies = [ "packaging", "sphinx>=9.1" ]
 # The extension stack of `scverse_doc.config`.
 optional-dependencies.config = [
   "myst-nb>=1.1",
@@ -34,7 +34,8 @@ optional-dependencies.config = [
   "sphinxext-opengraph",
 ]
 # Everything, as the `scverse_doc` extension needs.
-optional-dependencies.full = [ "scverse-doc[config,theme]" ]
+optional-dependencies.full = [ "scverse-doc[config,math-core,theme]" ]
+optional-dependencies.math-core = [ "math-core" ]
 # `html_theme = "scverse"`, i.e. `scverse_doc.theme`.
 optional-dependencies.theme = [ "pydata-sphinx-theme>=0.23" ]
 # https://docs.pypi.org/project_metadata/#project-urls
@@ -64,6 +65,7 @@ doc = [
   "lightningcss-cli",            # to rebuild the theme’s stylesheet bundles
   "scverse-misc[sphinx]>=0.1.2",
   "sphinx-autodoc-typehints",
+  "sphinx-toolbox>=4.3.1",       # `rest-example` directive
   "sphinxcontrib-bibtex>=1",
 ]
 typecheck = [ "mypy", "types-docutils", "wenmode" ]  # wenmode for scripts/check_changelog.py

diff --git a/scripts/sync_brand_tokens.py → scripts/sync_upstream.py b/scripts/sync_brand_tokens.py → scripts/sync_upstream.py
@@ -4,7 +4,7 @@
 # requires-python = ">=3.12"
 # dependencies = []
 # ///
-"""Refresh the generated brand assets from the scverse website.
+"""Refresh the files generated or copied from upstream: the scverse website and math-core.
 
 The website is the brand’s source of truth,
 so transcribing its colours into this repository by hand
@@ -20,9 +20,11 @@
 The scverse logo used for the navbar link back to the website is copied verbatim for the same reason,
 as is ``accents.json``, which the registry reads the package accents from.
 
+math-core’s stylesheet fixing browsers’ MathML rendering is copied verbatim from its repository.
+
 Usage
 -----
-    uv run scripts/sync_brand_tokens.py --website ../scverse.github.io
+    uv run scripts/sync_upstream.py --website ../scverse.github.io --math-core ../math-core
 """
 
 from __future__ import annotations
@@ -43,6 +45,11 @@
     Path("assets/accents.json"): HERE.parent / "src" / "scverse_doc" / "_accents.json",
 }
 
+#: math-core file -> package file, copied verbatim.
+MATH_CORE_ASSETS = {
+    Path("css/mathmlfixes.css"): HERE.parent / "src" / "scverse_doc" / "static" / "mathmlfixes.css",
+}
+
 #: CSS custom property emitted here -> website custom property it is resolved from.
 #: The pairing mirrors the one scverse/scverse.github.io#329 used when replacing its SCSS variables.
 TOKEN_MAP = {
@@ -66,7 +73,7 @@
     "--scverse-color-gradient-end": ("scverse", "sky-blue"),
 }
 
-BEGIN = "/* BEGIN GENERATED BRAND TOKENS – DO NOT EDIT; regenerate with scripts/sync_brand_tokens.py */"
+BEGIN = "/* BEGIN GENERATED BRAND TOKENS – DO NOT EDIT; regenerate with scripts/sync_upstream.py */"
 END = "/* END GENERATED BRAND TOKENS */"
 
 #: The fenced region, captured together with the indentation of its opening marker.
@@ -114,6 +121,7 @@ def main() -> int:
     """Write the refreshed token stylesheet to disk."""
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--website", type=Path, required=True, help="checkout of scverse/scverse.github.io")
+    parser.add_argument("--math-core", type=Path, required=True, help="checkout of tmke8/math-core")
     parser.add_argument("--check", action="store_true", help="fail instead of writing if the output would change")
     args = parser.parse_args()
 
@@ -122,10 +130,11 @@ def main() -> int:
     updates = {
         TARGET: render(props, accents, TARGET.read_text()).encode(),
         **{dst: (args.website / src).read_bytes() for src, dst in ASSETS.items()},
+        **{dst: (args.math_core / src).read_bytes() for src, dst in MATH_CORE_ASSETS.items()},
     }
     if args.check:
         if outdated := [str(dst) for dst, new in updates.items() if not dst.is_file() or dst.read_bytes() != new]:
-            print(f"{', '.join(outdated)} out of date; rerun scripts/sync_brand_tokens.py", file=sys.stderr)
+            print(f"{', '.join(outdated)} out of date; rerun scripts/sync_upstream.py", file=sys.stderr)
             return 1
         return 0
     for dst, new in updates.items():

diff --git a/src/scverse_doc/__init__.py b/src/scverse_doc/__init__.py
@@ -16,6 +16,8 @@
     The layout of the API pages.
 :mod:`scverse_doc.config`
     The extension stack and the shared defaults.
+:mod:`scverse_doc.math_core`
+    Math rendered to MathML at build time, via math-core.
 :mod:`scverse_doc.napoleon`
     Prose return sections in NumPy-style docstrings.
 :mod:`scverse_doc.registry`
@@ -40,7 +42,7 @@
 
 from sphinx.util.typing import ExtensionMetadata
 
-from . import autodoc, config, napoleon, registry, release_notes, source, theme, typed_fields, xref_overrides
+from . import autodoc, config, math_core, napoleon, registry, release_notes, source, theme, typed_fields, xref_overrides
 from .config import _is_set_by_user
 
 if TYPE_CHECKING:
@@ -50,6 +52,7 @@
 __all__ = [
     "autodoc",
     "config",
+    "math_core",
     "napoleon",
     "registry",
     "release_notes",