rootfig 0.3.0__tar.gz → 0.5.0__tar.gz

{rootfig-0.3.0 → rootfig-0.5.0}/CONTRIBUTING.md

@@ -36,7 +36,7 @@ tests that require ROOT or network access.
 
 ```
 src/rootfig/
-  api.py          plot(), histogram(), load(), ...  (orchestration only)
+  api/            plot(), histogram(), load(), ...  (orchestration only)
   errors.py       exception hierarchy
   expressions/    parse, validate and evaluate expression strings
   io/             file and in-memory data sources
@@ -90,32 +90,43 @@ f.Close()
 ## Figures and the gallery
 
 The `examples/gallery` package is both the showcase and the image-regression
-suite: `__init__.py` holds the shared `define()` block and the examples, `data.py`
-writes the toy files and `registry.py` extracts the source shown in the docs. Each
-example is a small function returning a `Plot`; `docs/gallery.md` shows every
-figure next to that function's source (a MkDocs hook, `docs/hooks/gallery.py`),
-and `tests/test_gallery.py` renders all of them and, with `--mpl`, compares
+suite: `__init__.py` holds the shared `define()` block, the `STYLES` and the
+examples, `data.py` writes the toy files and `registry.py` extracts the source
+shown in the docs. Each example is a small function returning a `Plot`. The
+MkDocs hook `docs/hooks/gallery.py` turns them into the gallery: an overview
+(`docs/gallery/index.md`, a card per example, section by section) and a
+generated page per example with its figure and complete code, one tab per
+style. `tests/test_gallery.py` renders all of them and, with `--mpl`, compares
 them pixel-wise (pytest-mpl, RMS tolerance 2) against `docs/images/gallery/`.
-Those PNGs are therefore the documentation images *and* the baselines.
+An example whose function takes a `style` is rendered in every entry of
+`STYLES` (the neutral default, ATLAS, CMS, LHCb, ALICE, DUNE) as
+`<name>-<style>.png`, `<name>.png` for the default; every rendering is made
+twice, as shown and inside `rf.dark_theme()` (`-dark`), and the docs pick one
+per palette. Those PNGs are therefore the documentation images *and* the
+baselines. The experiment styles are drawn only when images are compared or
+generated, and `-n auto` runs that on every core.
 
 ```bash
-MPLBACKEND=Agg uv run python examples/gallery             # look at examples/out/*.png
-uv run pytest tests/test_gallery.py --mpl                 # compare against the baselines
-uv run pytest tests/test_gallery.py --mpl-generate-path=docs/images/gallery   # accept changes
+MPLBACKEND=Agg uv run python examples/gallery               # look at examples/out/*.png
+MPLBACKEND=Agg uv run python examples/gallery --style CMS   # ... in another style
+uv run pytest tests/test_gallery.py --mpl -n auto           # compare against the baselines
+uv run pytest tests/test_gallery.py -n auto --mpl-generate-path=docs/images/gallery   # accept changes
 ```
 
 After any visual change: regenerate the baselines, open the PNGs and check
 them by eye, and commit them with the code. CI compares on Linux only (fonts
 differ elsewhere) and, when a comparison fails, uploads an HTML report with
 baseline, result and difference images as the `mpl-results-*` artifact. To add
-an example, register a function with `@example(name, title)` and give it a
-docstring; the test suite fails until its baseline image exists. Its parameters
-are attribute names of `Dataset`, it runs inside the directory holding the toy
-files (so name them `"signal.root"`, never through a variable), and the hook
-prints only the body (blank lines and comments included) — write it as a user
-would. Put an object into `define()` — the *Setup* block of the docs page — only
-when several examples use it; anything a single example needs belongs in that
-example.
+an example, register a function with `@example(name, title, section=...)` and
+give it a docstring; the test suite fails until its baseline images exist. Its
+parameters are attribute names of `Dataset`, plus `style` when the figure should
+be shown in every style (pass it on as `style=style`; leave it out when a style
+is the point of the example or the figure goes into axes of your own). It runs
+inside the directory holding the toy files (so name them `"signal.root"`, never
+through a variable), and the hook prints only the body (blank lines and
+comments included) — write it as a user would. Put an object into `define()` —
+the *Setup* block of the example pages — only when several examples use it;
+anything a single example needs belongs in that example.
 
 ## Pull requests
 

{rootfig-0.3.0 → rootfig-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rootfig
-Version: 0.3.0
+Version: 0.5.0
 Summary: Publication-quality figures straight from ROOT trees, without ROOT: uproot + Awkward + hist + mplhep with a TTree::Draw-like API.
 Project-URL: Homepage, https://github.com/jbeirer/rootfig
 Project-URL: Documentation, https://jbeirer.github.io/rootfig/
@@ -73,19 +73,20 @@ panels as your analysis grows. Every plot gives you a matplotlib figure to
 customise and save.
 
 <p align="center">
-  <a href="https://jbeirer.github.io/rootfig/gallery/#logarithmic-axes-with-log-spaced-bins"><img src="docs/images/gallery/log_axes.png" alt="Logarithmic axes with log-spaced bins" width="46%"></a>
+  <a href="https://jbeirer.github.io/rootfig/gallery/log_axes/"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/images/gallery/log_axes-dark.png"><img src="docs/images/gallery/log_axes.png" alt="Logarithmic axes with log-spaced bins" width="46%"></picture></a>
   &nbsp;&nbsp;
-  <a href="https://jbeirer.github.io/rootfig/gallery/#a-broken-x-axis-peak-and-far-tail-without-the-empty-middle"><img src="docs/images/gallery/xbreak_ratio.png" alt="Broken x axis with a ratio panel" width="46%"></a>
+  <a href="https://jbeirer.github.io/rootfig/gallery/hist2d/"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/images/gallery/hist2d-dark.png"><img src="docs/images/gallery/hist2d.png" alt="Two-dimensional histogram" width="46%"></picture></a>
 </p>
 <p align="center">
-  <a href="https://jbeirer.github.io/rootfig/gallery/#a-correlation-matrix"><img src="docs/images/gallery/correlation.png" alt="A correlation matrix" width="46%"></a>
+  <a href="https://jbeirer.github.io/rootfig/gallery/xbreak_ratio/#atlas"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/images/gallery/xbreak_ratio-atlas-dark.png"><img src="docs/images/gallery/xbreak_ratio-atlas.png" alt="Broken x axis with a ratio panel" width="46%"></picture></a>
   &nbsp;&nbsp;
-  <a href="https://jbeirer.github.io/rootfig/gallery/#a-two-dimensional-histogram"><img src="docs/images/gallery/hist2d.png" alt="Two-dimensional histogram" width="46%"></a>
+  <a href="https://jbeirer.github.io/rootfig/gallery/luminosity/"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/images/gallery/luminosity-dark.png"><img src="docs/images/gallery/luminosity.png" alt="FCC-ee stack scaled to luminosity with a significance panel" width="43%"></picture></a>
 </p>
 
 **[Explore the gallery →](https://jbeirer.github.io/rootfig/gallery/)**
 See each figure alongside the code that makes it, from simple overlays to
-stacked data/MC comparisons, broken axes and 2D histograms.
+stacked data/MC comparisons, broken axes and 2D histograms, in the neutral
+style or in that of ATLAS, CMS, LHCb, ALICE or DUNE.
 
 ## Installation
 
@@ -159,6 +160,10 @@ matplotlib `Figure`/`Axes`, `p.hists` are `hist.Hist` objects, and
   and `(n, low, high)` are used as given, while a range inferred from the data
   ignores far outliers, so `-999` sentinels do not set the axis. Normalise to
   unity, density, bin width or luminosity.
+- **Show systematic uncertainties.** Attach weight, branch, file or
+  normalisation variations to a sample; stacks and ratio panels draw the
+  combined statistical and systematic band, and every component stays
+  accessible.
 - **Style figures for your analysis.** Add experiment labels, units, log axes
   and broken axes, then refine the result with matplotlib.
 - **Go beyond 1D plots.** Draw 2D histograms, correlations, efficiencies,
@@ -209,6 +214,21 @@ uv run mypy
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
 
+## Citation
+
+If `rootfig` is useful in your research, please cite it:
+
+```bibtex
+@software{rootfig,
+  author = {Beirer, Joshua Falco},
+  doi = {10.5281/zenodo.22726311},
+  license = {MIT},
+  title = {{rootfig}},
+  url = {https://github.com/jbeirer/rootfig},
+  year = {2026}
+}
+```
+
 ## License
 
 MIT. See [LICENSE](LICENSE).

{rootfig-0.3.0 → rootfig-0.5.0}/README.md

@@ -40,19 +40,20 @@ panels as your analysis grows. Every plot gives you a matplotlib figure to
 customise and save.
 
 <p align="center">
-  <a href="https://jbeirer.github.io/rootfig/gallery/#logarithmic-axes-with-log-spaced-bins"><img src="docs/images/gallery/log_axes.png" alt="Logarithmic axes with log-spaced bins" width="46%"></a>
+  <a href="https://jbeirer.github.io/rootfig/gallery/log_axes/"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/images/gallery/log_axes-dark.png"><img src="docs/images/gallery/log_axes.png" alt="Logarithmic axes with log-spaced bins" width="46%"></picture></a>
   &nbsp;&nbsp;
-  <a href="https://jbeirer.github.io/rootfig/gallery/#a-broken-x-axis-peak-and-far-tail-without-the-empty-middle"><img src="docs/images/gallery/xbreak_ratio.png" alt="Broken x axis with a ratio panel" width="46%"></a>
+  <a href="https://jbeirer.github.io/rootfig/gallery/hist2d/"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/images/gallery/hist2d-dark.png"><img src="docs/images/gallery/hist2d.png" alt="Two-dimensional histogram" width="46%"></picture></a>
 </p>
 <p align="center">
-  <a href="https://jbeirer.github.io/rootfig/gallery/#a-correlation-matrix"><img src="docs/images/gallery/correlation.png" alt="A correlation matrix" width="46%"></a>
+  <a href="https://jbeirer.github.io/rootfig/gallery/xbreak_ratio/#atlas"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/images/gallery/xbreak_ratio-atlas-dark.png"><img src="docs/images/gallery/xbreak_ratio-atlas.png" alt="Broken x axis with a ratio panel" width="46%"></picture></a>
   &nbsp;&nbsp;
-  <a href="https://jbeirer.github.io/rootfig/gallery/#a-two-dimensional-histogram"><img src="docs/images/gallery/hist2d.png" alt="Two-dimensional histogram" width="46%"></a>
+  <a href="https://jbeirer.github.io/rootfig/gallery/luminosity/"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/images/gallery/luminosity-dark.png"><img src="docs/images/gallery/luminosity.png" alt="FCC-ee stack scaled to luminosity with a significance panel" width="43%"></picture></a>
 </p>
 
 **[Explore the gallery →](https://jbeirer.github.io/rootfig/gallery/)**
 See each figure alongside the code that makes it, from simple overlays to
-stacked data/MC comparisons, broken axes and 2D histograms.
+stacked data/MC comparisons, broken axes and 2D histograms, in the neutral
+style or in that of ATLAS, CMS, LHCb, ALICE or DUNE.
 
 ## Installation
 
@@ -126,6 +127,10 @@ matplotlib `Figure`/`Axes`, `p.hists` are `hist.Hist` objects, and
   and `(n, low, high)` are used as given, while a range inferred from the data
   ignores far outliers, so `-999` sentinels do not set the axis. Normalise to
   unity, density, bin width or luminosity.
+- **Show systematic uncertainties.** Attach weight, branch, file or
+  normalisation variations to a sample; stacks and ratio panels draw the
+  combined statistical and systematic band, and every component stays
+  accessible.
 - **Style figures for your analysis.** Add experiment labels, units, log axes
   and broken axes, then refine the result with matplotlib.
 - **Go beyond 1D plots.** Draw 2D histograms, correlations, efficiencies,
@@ -176,6 +181,21 @@ uv run mypy
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
 
+## Citation
+
+If `rootfig` is useful in your research, please cite it:
+
+```bibtex
+@software{rootfig,
+  author = {Beirer, Joshua Falco},
+  doi = {10.5281/zenodo.22726311},
+  license = {MIT},
+  title = {{rootfig}},
+  url = {https://github.com/jbeirer/rootfig},
+  year = {2026}
+}
+```
+
 ## License
 
 MIT. See [LICENSE](LICENSE).

{rootfig-0.3.0 → rootfig-0.5.0}/docs/api.md

@@ -18,6 +18,7 @@
 ::: rootfig.ratio
 ::: rootfig.log_bins
 ::: rootfig.use_style
+::: rootfig.dark_theme
 
 ## Descriptions
 
@@ -25,12 +26,14 @@
 ::: rootfig.Variable
 ::: rootfig.Cut
 ::: rootfig.Style
+::: rootfig.Systematic
 
 ## Results
 
 ::: rootfig.Plot
 ::: rootfig.Histogram
 ::: rootfig.Ratio
+::: rootfig.Uncertainty
 ::: rootfig.Summary
 ::: rootfig.SummaryTable
 ::: rootfig.Cutflow

{rootfig-0.3.0 → rootfig-0.5.0}/docs/composable.md

@@ -28,8 +28,9 @@ mem = rf.Sample({"x": awkward_array, "w": weights}, label="in memory")
   implementing the [`Source`][rootfig.io.Source] protocol.
 - `selection` and `weight` belong to the sample and combine with the ones
   given to `plot()` (`&` and `*` respectively).
-- `is_data=True` draws black points with error bars, keeps the sample out of
-  stacks and makes it the numerator of ratios.
+- `is_data=True` draws points with error bars (in the style's text colour
+  unless `color` is set), keeps the sample out of stacks and makes it the
+  numerator of ratios.
 - `xsec` and `ngen` describe simulated processes: the cross section (pb, or a
   string with a unit such as `"1.2 fb"`) and the number of generated events (a
   number, the name of an object in the file holding it, e.g. FCCAnalyses'
@@ -48,7 +49,14 @@ mem = rf.Sample({"x": awkward_array, "w": weights}, label="in memory")
   (a plot reads every needed branch of every file into memory at once). For a
   ready-made `FileSource`, give the range to the source itself; passing it to
   `Sample` afterwards raises a [`SourceError`][rootfig.SourceError].
-- `sample.with_(label="...")` returns a modified copy; replacement values are
+- `systematics={name: variation}` lists the sample's sources of systematic
+  uncertainty: weight expressions (`("w_up", "w_down")`), normalisation
+  uncertainties (`0.05`, `(1.1, 0.95)`), varied branches
+  (`{"Jet_pt": ("Jet_pt_up", "Jet_pt_down")}`) and varied files
+  ([`Systematic.samples`][rootfig.Systematic]). Sources with
+  the same name are correlated across samples; see
+  [Systematic uncertainties](plotting.md#systematic-uncertainties).
+- `sample.replace(label="...")` returns a copy with the given fields changed; new values are
   validated like constructor arguments.
 
 Passing a list of files to `plot()` creates one sample per file. To merge
@@ -113,8 +121,12 @@ neutral = rf.Style(
   given.
 - `base` can be any mplhep or matplotlib style name (`"ATLAS"`, `"ggplot"`,
   ...) or a mapping of rcParams; `rc` adds overrides on top; `colors` replaces
-  the colour cycle. `label_loc` is mplhep's label position (0 above the axes,
-  1 to 4 inside the corners), overriding the experiment's convention.
+  the colour cycle. `label_loc` overrides the experiment's convention: 0 puts
+  the experiment and secondary text above the frame; 3 puts the experiment
+  above and secondary text inside; 1, 2, and 4 put both inside. Luminosity stays
+  above for locations 0–3 and inside for 4. 2D histograms and correlation
+  matrices default to location 0; only `label_loc=1`, `2`, or `4` moves the
+  experiment inside the frame.
 - The centre-of-mass energy and luminosity appear only when `com`/`lumi` are
   given; nothing is invented for you.
 - `legend` is `True`, `False` or a location string; `legend_kwargs` are

rootfig-0.5.0/docs/gallery/index.md

@@ -0,0 +1,67 @@
+---
+hide:
+  - toc
+---
+
+# Gallery
+
+Every figure below is drawn by the code on its page. Most examples use a toy
+ROOT dataset: three simulated processes and one "observed" sample with muons,
+jets and event-level quantities. The in-memory arrays example generates its
+own NumPy data.
+
+Choose a style: examples with style tabs follow your choice here and on their
+individual pages. The other examples keep their own styles.
+
+<!-- gallery-overview -->
+
+## Run the examples
+
+The examples live in
+[`examples/gallery`](https://github.com/jbeirer/rootfig/blob/main/examples/gallery/__init__.py),
+and one command writes the toy files and every figure in a few seconds:
+
+```bash
+python examples/gallery                # everything ends up in examples/out/
+python examples/gallery --style CMS    # CMS for examples with style tabs
+```
+
+Each picture is also the reference image the test suite compares against, so
+what you see is what the current release draws.
+
+## Beyond figures
+
+The same inputs feed tables and arrays (`mc` and `signal` are the samples from
+the setup block of the example pages):
+
+```python
+# entries, mean, std, sem, skewness, min, max per sample and variable
+print(rf.summarize(mc, ["MET", "Muon_pt"], selection="nMuon > 0"))
+
+# a cut flow: yields, raw counts and step efficiencies per sample
+print(
+    rf.cutflow(
+        mc,
+        ["nMuon >= 2", rf.Cut("MET > 50", label="MET > 50 GeV"), "any(Jet_btag > 0.8)"],
+    )
+)
+
+# evaluated expressions as an Awkward record array
+events = rf.load(signal, ["MET", "count(Muon_pt)", "first(Muon_pt)"], selection="nJet >= 2")
+events["MET"]
+
+# a plain hist.Hist to feed into your own code
+h = rf.histogram(signal, "MET", bins=(40, 0, 400), selection="nJet >= 2")
+```
+
+Cuts compose with `&`, `|` and `~`, carry optional labels, and combine with
+selections given to `plot()`:
+
+```python
+base = rf.Cut("nMuon >= 2", label="2 muons")
+signal_region = base & "abs(Muon_eta) < 2.4" & ~rf.Cut("any(Jet_btag > 0.8)")
+control_region = base & rf.Cut("any(Jet_btag > 0.8)") | "MET > 200"
+```
+
+See [Plotting options](../plotting.md) for every keyword and
+[Expressions and selections](../expressions.md) for the per-event/per-object rules.

rootfig-0.5.0/docs/hooks/gallery.py

@@ -0,0 +1,251 @@
+"""MkDocs hook that builds the gallery pages from the ``examples/gallery`` package.
+
+The gallery is an overview page and one page per example, all made from the
+registry:
+
+``gallery/index.md``
+    carries the ``<!-- gallery-overview -->`` marker, replaced by one tab per
+    gallery style, each holding the examples section by section as a grid of
+    cards (thumbnail and title, linking to the example's page);
+``gallery/<name>.md``
+    generated for every example (``on_files``), with no file in ``docs/``: the
+    title, the description, one tab per style the example is drawn in with its
+    image (``docs/images/gallery/<name>[-<style>].png``, and ``-dark`` for the
+    dark palette, switched by Material's ``#only-light``/``#only-dark``) and the
+    complete code, and the setup block the code relies on.
+
+The Gallery entry of the navigation, ``gallery/index.md``, becomes a section with
+the overview and the example pages, grouped like the overview (``on_config``).
+Every tab set uses the same labels, so Material's ``content.tabs.link`` switches
+all figures on all pages together. Tabs, cards and the setup block are
+pymdownx blocks, which nest without indentation.
+
+The gallery module is imported, never executed, so building the docs needs no
+data and draws nothing. Because the images are also the baselines of
+``tests/test_gallery.py``, picture and code cannot drift apart.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import re
+import sys
+import textwrap
+from collections.abc import Iterable, Sequence
+from pathlib import Path
+from types import ModuleType
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:  # MkDocs runs the hook; the tests import it without MkDocs installed
+    from mkdocs.config.defaults import MkDocsConfig
+    from mkdocs.structure.files import Files
+
+ROOT = Path(__file__).resolve().parents[2]
+GALLERY_DIR = ROOT / "examples" / "gallery"
+OVERVIEW = "gallery/index.md"
+OVERVIEW_MARKER = "<!-- gallery-overview -->"
+IMAGES = "../images/gallery"  # relative to the gallery pages
+
+
+def _load_gallery(name: str = "rootfig_gallery_docs") -> ModuleType:
+    """Import ``examples/gallery`` as a fresh package, without ``examples/`` on ``sys.path``.
+
+    Every call re-executes the package (``mkdocs serve`` rebuilds on each change),
+    so its submodules are evicted from ``sys.modules`` first: a cached
+    ``registry`` would keep its ``EXAMPLES`` list and the re-run decorators would
+    register every example a second time.
+    """
+    for cached in [m for m in sys.modules if m == name or m.startswith(f"{name}.")]:
+        del sys.modules[cached]
+    spec = importlib.util.spec_from_file_location(
+        name, GALLERY_DIR / "__init__.py", submodule_search_locations=[str(GALLERY_DIR)]
+    )
+    if spec is None or spec.loader is None:
+        msg = f"cannot load {GALLERY_DIR}"
+        raise RuntimeError(msg)
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+# --------------------------------------------------------------------------------------
+# MkDocs events
+# --------------------------------------------------------------------------------------
+
+
+def on_config(config: MkDocsConfig) -> MkDocsConfig:
+    """Turn the navigation's gallery entry into the gallery section."""
+    if config.nav is not None:
+        config.nav = gallery_nav(config.nav, _load_gallery())
+    return config
+
+
+def on_files(files: Files, config: MkDocsConfig) -> Files:
+    """Add a generated page for every example."""
+    from mkdocs.structure.files import File  # noqa: PLC0415 - only MkDocs calls this
+
+    gallery = _load_gallery()
+    for example in gallery.EXAMPLES:
+        content = render_page(gallery, example)
+        files.append(File.generated(config, page_path(example), content=content))
+    return files
+
+
+def on_page_markdown(markdown: str, **_: Any) -> str:
+    """Expand the overview marker (MkDocs ``on_page_markdown`` event)."""
+    if OVERVIEW_MARKER not in markdown:
+        return markdown
+    return markdown.replace(OVERVIEW_MARKER, render_overview(_load_gallery()))
+
+
+# --------------------------------------------------------------------------------------
+# Navigation
+# --------------------------------------------------------------------------------------
+
+
+def page_path(example: Any) -> str:
+    """Path of an example's page, relative to ``docs/``."""
+    return f"gallery/{example.name}.md"
+
+
+def sections(examples: Iterable[Any]) -> dict[str, list[Any]]:
+    """Group ``examples`` by section, sections in order of their first example."""
+    grouped: dict[str, list[Any]] = {}
+    for example in examples:
+        grouped.setdefault(example.section, []).append(example)
+    return grouped
+
+
+def gallery_nav(nav: Sequence[Any], gallery: ModuleType) -> list[Any]:
+    """Return ``nav`` with its ``gallery/index.md`` entry expanded into the gallery section."""
+    pages = [
+        {title: [page_path(example) for example in examples]}
+        for title, examples in sections(gallery.EXAMPLES).items()
+    ]
+
+    def expand(item: Any) -> Any:
+        if isinstance(item, dict) and list(item.values()) == [OVERVIEW]:
+            return {title: [OVERVIEW, *pages] for title in item}
+        return item
+
+    return [expand(item) for item in nav]
+
+
+# --------------------------------------------------------------------------------------
+# Markdown
+# --------------------------------------------------------------------------------------
+
+
+def render_overview(gallery: ModuleType) -> str:
+    """One tab per gallery style; each holds every section's cards in that style."""
+    grouped = sections(gallery.EXAMPLES)
+    tabs = []
+    for style in gallery.STYLES:
+        content = "\n\n".join(
+            _block("html", 'p.gallery-section[role="heading" aria-level="2"]', title, level=5)
+            + "\n\n"
+            + _block(
+                "html", "div.grid.cards.gallery-cards", _cards(gallery, examples, style), level=5
+            )
+            for title, examples in grouped.items()
+        )
+        tabs.append((style, content))
+    return _block("html", "div.gallery-overview", _tabs(tabs, level=4), level=3)
+
+
+def _cards(gallery: ModuleType, examples: Iterable[Any], style: str) -> str:
+    cards = []
+    for example in examples:
+        shown = style if style in gallery.styles_of(example) else gallery.DEFAULT_STYLE
+        images = _images(example, shown, alt="", width=None)
+        link = f"[{example.title}]({page_path(example).removeprefix('gallery/')})"
+        card = textwrap.indent(f"{images}\n\n{link}", "    ")
+        cards.append(f"-{card[1:]}")  # the list marker takes the first indent's place
+    return "\n\n".join(cards)
+
+
+def render_page(gallery: ModuleType, example: Any) -> str:
+    """The page of one example: title, description, figure and code per style, setup."""
+    figures = [
+        (style, _figure(gallery, example, style if example.styled else None))
+        for style in gallery.styles_of(example)
+    ]
+    shown = _tabs(figures, level=3) if example.styled else figures[0][1]
+    # no table of contents (a page has one heading), so figure and code get its width
+    parts = ["---\nhide:\n  - toc\n---", f"# {example.title}", example.description, shown]
+    setup = _setup(gallery, example)
+    return "\n\n".join([*parts, *([setup] if setup else [])]) + "\n"
+
+
+def _figure(gallery: ModuleType, example: Any, style: str | None) -> str:
+    """The image pair and the complete code of ``example`` in ``style`` (``None``: unstyled)."""
+    alt = example.title if style is None else f"{example.title}, {style} style"
+    images = _images(example, style or gallery.DEFAULT_STYLE, alt=alt, width=example.image_width)
+    code, highlighted = example_code(gallery, example, style)
+    options = f' hl_lines="{" ".join(map(str, highlighted))}"' if highlighted else ""
+    figure = _block("html", "figure.gallery-figure", images, level=4)
+    return f"{figure}\n\n```python{options}\n{code}```"
+
+
+def _images(example: Any, style: str, *, alt: str, width: str | None) -> str:
+    """Markdown for the light and the dark image of ``example`` in ``style``, lazily loaded."""
+    attributes = f'width="{width}" loading=lazy' if width else "loading=lazy"
+    return "\n".join(
+        f"![{alt}]({IMAGES}/{example.image(style, dark=dark)}#only-{theme}){{ {attributes} }}"
+        for dark, theme in ((False, "light"), (True, "dark"))
+    )
+
+
+def example_code(gallery: ModuleType, example: Any, style: str | None) -> tuple[str, list[int]]:
+    """The code shown for ``example``, and the numbers of the lines to highlight.
+
+    It starts with the imports the body uses and, for a style, the line that makes
+    that style; the highlighted lines are that line and those passing it on, so
+    switching tabs shows exactly what changes.
+    """
+    body = gallery.body_source(example.func).splitlines()
+    imports = [
+        f"import {module} as {alias}"
+        for module, alias in (("matplotlib.pyplot", "plt"), ("numpy", "np"))
+        if any(re.search(rf"\b{alias}\.", text) for text in body)
+    ]
+    lines = [*imports, "import rootfig as rf", ""]
+    highlighted = []
+    if style is not None:
+        lines += [f"style = {gallery.style_source(gallery.STYLES[style])}", ""]
+        highlighted.append(len(lines) - 1)
+        highlighted += [len(lines) + n for n, text in enumerate(body, 1) if "style=style" in text]
+    return "\n".join([*lines, *body]) + "\n", highlighted
+
+
+def _setup(gallery: ModuleType, example: Any) -> str | None:
+    """How to run ``example``: where the toy files come from, and the definitions it uses."""
+    shared = any(name != "style" for name in example.parameters)
+    parts = []
+    if example.toy_data:
+        parts.append(
+            "The code reads the toy dataset. In a checkout of "
+            "[rootfig](https://github.com/jbeirer/rootfig), `python examples/gallery` writes "
+            "it to `examples/out/` in a few seconds; run the code inside that directory."
+        )
+    if shared:
+        code = gallery.body_source(gallery.define, returns="omit")
+        parts.append(
+            "It uses these samples and variables, shared by the gallery examples (see "
+            f"[Samples, variables, cuts and styles](../composable.md)):\n\n```python\n{code}```"
+        )
+    if not parts:
+        return None
+    return _block("details", "Setup", "\n\n".join(parts), level=3, options="type: abstract")
+
+
+def _tabs(tabs: Iterable[tuple[str, str]], *, level: int) -> str:
+    return "\n\n".join(_block("tab", label, content, level=level) for label, content in tabs)
+
+
+def _block(kind: str, argument: str, content: str, *, level: int, options: str = "") -> str:
+    """A pymdownx block; nested blocks need more slashes than the block around them."""
+    fence = "/" * level
+    header = f"{fence} {kind} | {argument}" + (f"\n    {options}" if options else "")
+    return f"{header}\n\n{content}\n\n{fence}"