rootfig 0.2.0__tar.gz → 0.2.2__tar.gz

{rootfig-0.2.0 → rootfig-0.2.2}/CONTRIBUTING.md

@@ -89,7 +89,9 @@ f.Close()
 
 ## Figures and the gallery
 
-`examples/gallery.py` is both the showcase and the image-regression suite. Each
+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
@@ -97,7 +99,7 @@ them pixel-wise (pytest-mpl, RMS tolerance 2) against `docs/images/gallery/`.
 Those PNGs are therefore the documentation images *and* the baselines.
 
 ```bash
-MPLBACKEND=Agg uv run python examples/gallery.py          # look at examples/out/*.png
+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
 ```
@@ -107,7 +109,13 @@ 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.
+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.
 
 ## Pull requests
 

{rootfig-0.2.0 → rootfig-0.2.2}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.5
 Name: rootfig
-Version: 0.2.0
+Version: 0.2.2
 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://github.com/jbeirer/rootfig#readme
+Project-URL: Documentation, https://jbeirer.github.io/rootfig/
 Project-URL: Repository, https://github.com/jbeirer/rootfig
 Project-URL: Issues, https://github.com/jbeirer/rootfig/issues
 Author-email: Joshua Falco Beirer <jbeirer@cern.ch>
@@ -35,41 +35,42 @@ Description-Content-Type: text/markdown
 
 **Publication-quality figures straight from ROOT trees, without ROOT.**
 
-`rootfig` is the `TTree::Draw` workflow for the Scientific Python HEP stack:
-give it ROOT files, a tree, an expression, a selection and a weight, and get a
-styled matplotlib figure back in one call. It reads with
-[uproot](https://github.com/scikit-hep/uproot5), computes with
-[Awkward Array](https://github.com/scikit-hep/awkward), fills
-[hist](https://github.com/scikit-hep/hist) histograms and draws with
-[mplhep](https://github.com/scikit-hep/mplhep). It adds the missing glue:
-predictable per-event/per-object selection semantics, weights, shared
-binning across samples, normalisation, ratio panels and good defaults.
-
+[![Docs](https://img.shields.io/badge/docs-online-blue)](https://jbeirer.github.io/rootfig/)
 [![CI](https://github.com/jbeirer/rootfig/actions/workflows/ci.yml/badge.svg)](https://github.com/jbeirer/rootfig/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/jbeirer/rootfig/branch/main/graph/badge.svg)](https://codecov.io/gh/jbeirer/rootfig)
 [![PyPI](https://img.shields.io/pypi/v/rootfig.svg)](https://pypi.org/project/rootfig/)
 [![Python](https://img.shields.io/pypi/pyversions/rootfig.svg)](https://pypi.org/project/rootfig/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
+**[Documentation](https://jbeirer.github.io/rootfig/) ·
+[Gallery](https://jbeirer.github.io/rootfig/gallery/) ·
+[Quick start](https://jbeirer.github.io/rootfig/quickstart/)**
+
+Go from ROOT files to a styled figure in one call. Choose a variable, add a
+selection, and plot:
+
 ```python
 import rootfig as rf
 
 rf.plot("events.root", "Muon_pt", tree="events", selection="Muon_pt > 20", bins=50)
 ```
 
+Start with a single distribution; add samples, weights, stacks and ratio
+panels as your analysis grows. Every plot gives you a matplotlib figure to
+customise and save. No ROOT installation required.
+
 <p align="center">
-  <img src="docs/images/gallery/stack_data.png" alt="Stacked simulation with data and a ratio panel" width="48%">
-  <img src="docs/images/gallery/xbreak_ratio.png" alt="Broken x axis with a ratio panel" width="48%">
+  <a href="https://jbeirer.github.io/rootfig/gallery/"><img src="docs/images/gallery/stack_data.png" alt="Stacked simulation with data and a ratio panel" width="48%"></a>
+  <a href="https://jbeirer.github.io/rootfig/gallery/"><img src="docs/images/gallery/xbreak_ratio.png" alt="Broken x axis with a ratio panel" width="48%"></a>
 </p>
 <p align="center">
-  <img src="docs/images/gallery/object_vs_event.png" alt="Per-object versus per-event selections" width="48%">
-  <img src="docs/images/gallery/hist2d.png" alt="Two-dimensional histogram" width="48%">
+  <a href="https://jbeirer.github.io/rootfig/gallery/"><img src="docs/images/gallery/object_vs_event.png" alt="Per-object versus per-event selections" width="48%"></a>
+  <a href="https://jbeirer.github.io/rootfig/gallery/"><img src="docs/images/gallery/hist2d.png" alt="Two-dimensional histogram" width="48%"></a>
 </p>
 
-These and a dozen more figures, each next to the code that made it, are in the
-[gallery](https://jbeirer.github.io/rootfig/gallery/). All of them come from
-[`examples/gallery.py`](examples/gallery.py), which writes toy ROOT files and
-draws every example in a few seconds; the same figures are pixel-compared in CI.
+**[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.
 
 ## Installation
 
@@ -82,7 +83,7 @@ uv add rootfig
 Python 3.12 or newer. No ROOT installation is needed; `TTree` and `RNTuple`
 files are both supported.
 
-## Quick start
+## Compare samples in one call
 
 ```python
 import rootfig as rf
@@ -100,8 +101,9 @@ rf.plot(
 )
 ```
 
-For analysis scripts with many samples, variables and plots, describe things
-once and reuse them:
+## Build up to a full analysis
+
+Define samples, variables, cuts and styles once, then reuse them across plots:
 
 ```python
 import rootfig as rf
@@ -132,56 +134,50 @@ Everything you get back is a standard object: `p.fig` and `p.ax` are
 matplotlib `Figure`/`Axes`, `p.hists` are `hist.Hist` objects, and
 `rf.load(...)` returns Awkward arrays.
 
-## Features
-
-- **One call from files to figure**, reading only the branches the expressions need.
-- **Expressions in Python syntax**: `sqrt(px**2 + py**2)`, `count(Jet_pt) >= 2`,
-  `` `jet1_b-tag` > 0.5 ``, `and`/`or`/`not`, chained comparisons.
-- **Jagged branches done right**: per-object cuts mask objects, per-event
-  cuts drop events, ambiguous combinations raise a clear error instead of
-  silently broadcasting.
-- **Weights**: per-event weights broadcast onto objects, per-object weights,
-  constant scale factors, multiplicative combination of sample and plot weights.
-- **Histograms with uncertainties** (`hist` with `Weight` storage), shared
-  binning across samples, automatic or robust ranges, log bins, flow bins.
-- **Overlays, stacks, data points, ratio panels** with correct error
-  propagation for weighted histograms and a reference-uncertainty band.
-- **Normalisation**: to unity, density, per bin width, or to a number; or to
-  a **luminosity** from cross sections and generated-event counts
-  (`Sample(xsec="0.2 pb", ngen="eventsProcessed")`, `lumi="10.8 ab^-1"`).
-- **Analysis tables and panels**: cut flows with yields and efficiencies,
-  significance panels (S/√B), efficiency-versus-variable plots with binomial
-  intervals, profiles and resolutions.
-- **Experiment-neutral defaults**, with mplhep styles and labels for ATLAS,
-  CMS, LHCb, ALICE and DUNE one keyword away; any other experiment name, GeV
-  and ab⁻¹ work too.
-- **EDM4hep-friendly**: sub-branches of split collections are addressed as
-  `ReconstructedParticles.momentum.x`, with `pt`, `p`, `theta`, `costheta`,
-  `eta`, `phi` and `mass` helpers.
-- **Also**: 2D histograms, summary statistics tables, statistics boxes,
-  correlation matrices, multi-file globs, entry ranges for quick looks.
+## What you can do
+
+- **Select events and objects with readable expressions.** Write cuts such as
+  `count(Jet_pt) >= 2` or `Muon_pt > 20`; event and object selections have
+  explicit rules, and event weights carry through to each selected object.
+- **Compare samples with a few keywords.** Overlays, stacks, data points and
+  ratio panels share binning and propagate histogram uncertainties.
+  Normalise to unity, density, bin width or luminosity.
+- **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,
+  profiles, resolutions and significance panels; produce cut flows and
+  summary statistics from the same inputs.
+- **Work directly with your files.** Read `TTree` and `RNTuple` data, combine
+  files with globs, limit entry ranges for quick checks, and use EDM4hep
+  split collections. Only the branches your expressions need are read.
 
 ## Documentation
 
-- [Quick start](docs/quickstart.md)
-- [Expressions and selections](docs/expressions.md)
-- [Samples, variables, cuts and styles](docs/composable.md)
-- [Plotting options](docs/plotting.md)
-- [Relation to uproot, Awkward, hist, mplhep and matplotlib](docs/ecosystem.md)
+**[Read the docs](https://jbeirer.github.io/rootfig/)** or
+**[browse the gallery](https://jbeirer.github.io/rootfig/gallery/)** for examples
+with figures and code.
+
+- [Quick start](https://jbeirer.github.io/rootfig/quickstart/): your first plot, selections and weights.
+- [Expressions and selections](https://jbeirer.github.io/rootfig/expressions/): syntax and event/object rules.
+- [Samples, variables, cuts and styles](https://jbeirer.github.io/rootfig/composable/): reusable analysis definitions.
+- [Plotting options](https://jbeirer.github.io/rootfig/plotting/): binning, normalisation, panels and styling.
+- [API reference](https://jbeirer.github.io/rootfig/api/): full signatures and options.
 
 ## Relation to the ecosystem
 
-`rootfig` does not replace any of the libraries it builds on:
+`rootfig` brings a `TTree::Draw`-like workflow to the Scientific Python HEP
+stack, building on familiar libraries:
 
 | Task | Library | What rootfig adds |
 | --- | --- | --- |
-| Reading ROOT files | uproot | file globs, tree auto-detection, reading only the required branches |
-| Jagged arrays | Awkward Array | the per-event/per-object rules for cuts and weights |
-| Histograms | hist / boost-histogram | shared binning, automatic ranges, normalisation, ratios |
-| Drawing | mplhep + matplotlib | overlays, stacks, ratio panels, labels and legends with good defaults |
+| Reading ROOT files | [uproot](https://github.com/scikit-hep/uproot5) | file globs, tree auto-detection, reading only the required branches |
+| Jagged arrays | [Awkward Array](https://github.com/scikit-hep/awkward) | the per-event/per-object rules for cuts and weights |
+| Histograms | [hist](https://github.com/scikit-hep/hist) / boost-histogram | shared binning, automatic ranges, normalisation, ratios |
+| Drawing | [mplhep](https://github.com/scikit-hep/mplhep) + matplotlib | overlays, stacks, ratio panels, labels and legends with good defaults |
 
 If you already have `hist.Hist` objects, `rf.plot_histograms` draws them with
-the same options. If you want the arrays, `rf.load` returns them.
+the same options. If you want the arrays, `rf.load` returns them. See
+[the ecosystem guide](https://jbeirer.github.io/rootfig/ecosystem/) for details.
 
 ## Development
 

rootfig-0.2.2/README.md

@@ -0,0 +1,164 @@
+# rootfig
+
+**Publication-quality figures straight from ROOT trees, without ROOT.**
+
+[![Docs](https://img.shields.io/badge/docs-online-blue)](https://jbeirer.github.io/rootfig/)
+[![CI](https://github.com/jbeirer/rootfig/actions/workflows/ci.yml/badge.svg)](https://github.com/jbeirer/rootfig/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/jbeirer/rootfig/branch/main/graph/badge.svg)](https://codecov.io/gh/jbeirer/rootfig)
+[![PyPI](https://img.shields.io/pypi/v/rootfig.svg)](https://pypi.org/project/rootfig/)
+[![Python](https://img.shields.io/pypi/pyversions/rootfig.svg)](https://pypi.org/project/rootfig/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**[Documentation](https://jbeirer.github.io/rootfig/) ·
+[Gallery](https://jbeirer.github.io/rootfig/gallery/) ·
+[Quick start](https://jbeirer.github.io/rootfig/quickstart/)**
+
+Go from ROOT files to a styled figure in one call. Choose a variable, add a
+selection, and plot:
+
+```python
+import rootfig as rf
+
+rf.plot("events.root", "Muon_pt", tree="events", selection="Muon_pt > 20", bins=50)
+```
+
+Start with a single distribution; add samples, weights, stacks and ratio
+panels as your analysis grows. Every plot gives you a matplotlib figure to
+customise and save. No ROOT installation required.
+
+<p align="center">
+  <a href="https://jbeirer.github.io/rootfig/gallery/"><img src="docs/images/gallery/stack_data.png" alt="Stacked simulation with data and a ratio panel" width="48%"></a>
+  <a href="https://jbeirer.github.io/rootfig/gallery/"><img src="docs/images/gallery/xbreak_ratio.png" alt="Broken x axis with a ratio panel" width="48%"></a>
+</p>
+<p align="center">
+  <a href="https://jbeirer.github.io/rootfig/gallery/"><img src="docs/images/gallery/object_vs_event.png" alt="Per-object versus per-event selections" width="48%"></a>
+  <a href="https://jbeirer.github.io/rootfig/gallery/"><img src="docs/images/gallery/hist2d.png" alt="Two-dimensional histogram" width="48%"></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.
+
+## Installation
+
+```bash
+pip install rootfig
+# or
+uv add rootfig
+```
+
+Python 3.12 or newer. No ROOT installation is needed; `TTree` and `RNTuple`
+files are both supported.
+
+## Compare samples in one call
+
+```python
+import rootfig as rf
+
+# Overlay two samples, normalised to unity, with a ratio panel.
+rf.plot(
+    ["signal.root", "background.root"],
+    "Muon_pt",
+    tree="events",
+    selection="abs(Muon_eta) < 2.5",
+    weight="event_weight",
+    bins=(50, 0, 200),
+    normalize=True,
+    ratio=True,
+)
+```
+
+## Build up to a full analysis
+
+Define samples, variables, cuts and styles once, then reuse them across plots:
+
+```python
+import rootfig as rf
+
+signal = rf.Sample("sig_*.root", tree="events", label="Signal", weight="mc_weight")
+background = rf.Sample("bkg.root", tree="events", label="Background", weight="mc_weight")
+data = rf.Sample("data.root", tree="events", label="Data", is_data=True)
+
+pt = rf.Variable("Muon_pt", bins=(50, 0, 200), label=r"$p_T^{\mu}$", unit="GeV")
+baseline = rf.Cut("nMuon >= 1") & "abs(Muon_eta) < 2.5"
+style = rf.Style(experiment="ATLAS", status="Internal", lumi=140, com=13.6)
+
+p = rf.plot(
+    [background, signal],
+    pt,
+    observed=data,
+    selection=baseline,
+    stack=True,
+    ratio=True,
+    logy=True,
+    style=style,
+)
+p.ax.set_ylim(top=1e5)  # it is a normal matplotlib Axes
+p.save("muon_pt.pdf")
+```
+
+Everything you get back is a standard object: `p.fig` and `p.ax` are
+matplotlib `Figure`/`Axes`, `p.hists` are `hist.Hist` objects, and
+`rf.load(...)` returns Awkward arrays.
+
+## What you can do
+
+- **Select events and objects with readable expressions.** Write cuts such as
+  `count(Jet_pt) >= 2` or `Muon_pt > 20`; event and object selections have
+  explicit rules, and event weights carry through to each selected object.
+- **Compare samples with a few keywords.** Overlays, stacks, data points and
+  ratio panels share binning and propagate histogram uncertainties.
+  Normalise to unity, density, bin width or luminosity.
+- **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,
+  profiles, resolutions and significance panels; produce cut flows and
+  summary statistics from the same inputs.
+- **Work directly with your files.** Read `TTree` and `RNTuple` data, combine
+  files with globs, limit entry ranges for quick checks, and use EDM4hep
+  split collections. Only the branches your expressions need are read.
+
+## Documentation
+
+**[Read the docs](https://jbeirer.github.io/rootfig/)** or
+**[browse the gallery](https://jbeirer.github.io/rootfig/gallery/)** for examples
+with figures and code.
+
+- [Quick start](https://jbeirer.github.io/rootfig/quickstart/): your first plot, selections and weights.
+- [Expressions and selections](https://jbeirer.github.io/rootfig/expressions/): syntax and event/object rules.
+- [Samples, variables, cuts and styles](https://jbeirer.github.io/rootfig/composable/): reusable analysis definitions.
+- [Plotting options](https://jbeirer.github.io/rootfig/plotting/): binning, normalisation, panels and styling.
+- [API reference](https://jbeirer.github.io/rootfig/api/): full signatures and options.
+
+## Relation to the ecosystem
+
+`rootfig` brings a `TTree::Draw`-like workflow to the Scientific Python HEP
+stack, building on familiar libraries:
+
+| Task | Library | What rootfig adds |
+| --- | --- | --- |
+| Reading ROOT files | [uproot](https://github.com/scikit-hep/uproot5) | file globs, tree auto-detection, reading only the required branches |
+| Jagged arrays | [Awkward Array](https://github.com/scikit-hep/awkward) | the per-event/per-object rules for cuts and weights |
+| Histograms | [hist](https://github.com/scikit-hep/hist) / boost-histogram | shared binning, automatic ranges, normalisation, ratios |
+| Drawing | [mplhep](https://github.com/scikit-hep/mplhep) + matplotlib | overlays, stacks, ratio panels, labels and legends with good defaults |
+
+If you already have `hist.Hist` objects, `rf.plot_histograms` draws them with
+the same options. If you want the arrays, `rf.load` returns them. See
+[the ecosystem guide](https://jbeirer.github.io/rootfig/ecosystem/) for details.
+
+## Development
+
+```bash
+git clone https://github.com/jbeirer/rootfig
+cd rootfig
+uv sync --all-groups
+uv run pytest
+uv run ruff check . && uv run ruff format --check .
+uv run mypy
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

{rootfig-0.2.0 → rootfig-0.2.2}/docs/gallery.md

@@ -1,33 +1,40 @@
 # Gallery
 
 Every figure on this page is made by
-[`examples/gallery.py`](https://github.com/jbeirer/rootfig/blob/main/examples/gallery.py).
+[`examples/gallery`](https://github.com/jbeirer/rootfig/blob/main/examples/gallery/__init__.py).
 The script writes a toy dataset (three simulated processes and one "observed"
-sample with muons, jets and event-level quantities, as `TTree`s) and runs all
-examples in a few seconds:
+sample with muons, jets and event-level quantities, as `TTree`s) into a
+directory and runs all examples there in a few seconds:
 
 ```bash
-python examples/gallery.py            # figures end up in examples/out/
+python examples/gallery               # everything ends up in examples/out/
 ```
 
 The code next to each figure is the source of that example, and the image is
 the reference picture the test suite compares against, so what you see is what
-the current release draws.
+the current release draws. File names such as `signal.root` are those toy
+files, relative to that directory, and every example assumes
 
 ```python
-import matplotlib.pyplot as plt
-import numpy as np
-
 import rootfig as rf
 ```
 
+<!-- gallery: quick -->
+
 ## Setup
 
-The examples share a few definitions, made once (`out` is the directory with
-the toy files). Everything below is optional: plain strings work everywhere.
+Plain strings and `(bins, low, high)` tuples are accepted everywhere, as the
+one-liner shows. Once you draw more than one plot it pays to name the pieces:
+`Sample`, `Variable`, `Cut` and `Style` are small frozen dataclasses (see
+[Samples, variables, cuts and styles](composable.md)). The rest of this page
+shares four samples, three variables and one style, defined once:
 
 <!-- gallery-setup -->
 
+Anything a single example needs is defined inside that example, so every block
+below is complete given the names above (plus `matplotlib.pyplot as plt` and
+`numpy as np` where they appear).
+
 <!-- gallery -->
 
 ## Beyond figures
@@ -38,21 +45,20 @@ The same inputs feed tables and arrays:
 # 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 at a luminosity, raw counts and step efficiencies per sample
+# a cut flow: yields, raw counts and step efficiencies per sample
 print(
     rf.cutflow(
-        [zh, ww, zz],
+        mc,
         ["nMuon >= 2", rf.Cut("MET > 50", label="MET > 50 GeV"), "any(Jet_btag > 0.8)"],
-        lumi="10.8 ab^-1",
     )
 )
 
 # evaluated expressions as an Awkward record array
-events = rf.load(sig, ["MET", "count(Muon_pt)", "first(Muon_pt)"], selection="nJet >= 2")
+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(sig, "MET", bins=(40, 0, 400), selection="nJet >= 2")
+h = rf.histogram(signal, "MET", bins=(40, 0, 400), selection="nJet >= 2")
 ```
 
 Cuts compose with `&`, `|` and `~`, carry optional labels, and combine with

rootfig-0.2.2/docs/hooks/gallery.py

@@ -0,0 +1,98 @@
+"""MkDocs hook that fills ``docs/gallery.md`` from the ``examples/gallery`` package.
+
+Two kinds of marker are expanded when the page is rendered:
+
+``<!-- gallery-setup -->``
+    the body of ``define()``: the samples, variables and style shared by the
+    examples;
+``<!-- gallery -->`` / ``<!-- gallery: name ... -->``
+    one section per example with its title, description, image
+    (``docs/images/gallery/<name>.png``) and the source of the example
+    function. A marker naming examples renders exactly those, so a few can be
+    shown before the setup section; a bare marker renders everything that no
+    earlier marker on the page has shown yet, in registration order.
+
+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
+from pathlib import Path
+from types import ModuleType
+from typing import Any
+
+ROOT = Path(__file__).resolve().parents[2]
+GALLERY_DIR = ROOT / "examples" / "gallery"
+SETUP_MARKER = "<!-- gallery-setup -->"
+GALLERY_MARKER = re.compile(r"<!-- gallery(?::\s*(?P<names>[\w\s,]+?))?\s*-->")
+
+
+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`` renders the page on each
+    rebuild), 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
+
+
+def render_section(gallery: ModuleType, example: Any) -> str:
+    """Markdown for one example: heading, description, image, code."""
+    code = gallery.body_source(example.func)
+    return (
+        f"## {example.title}\n\n"
+        f"{example.description}\n\n"
+        f'![{example.title}](images/gallery/{example.name}.png){{ width="75%" }}\n\n'
+        f"```python\n{code}```\n"
+    )
+
+
+def expand_markers(markdown: str, gallery: ModuleType) -> str:
+    """Replace every gallery marker, each example going to the first marker that asks."""
+    shown: set[str] = set()
+    by_name = {example.name: example for example in gallery.EXAMPLES}
+
+    def replace(match: re.Match[str]) -> str:
+        names = match.group("names")
+        if names is None:
+            wanted = [ex.name for ex in gallery.EXAMPLES if ex.name not in shown]
+        else:
+            asked = names.replace(",", " ").split()
+            unknown = [name for name in asked if name not in by_name]
+            if unknown:
+                msg = f"unknown gallery example(s) {unknown} in {match.group(0)!r}"
+                raise ValueError(msg)
+            # first marker wins: skip what an earlier marker (or this one) already rendered
+            wanted = list(dict.fromkeys(name for name in asked if name not in shown))
+        shown.update(wanted)
+        return "\n".join(render_section(gallery, by_name[name]) for name in wanted)
+
+    return GALLERY_MARKER.sub(replace, markdown)
+
+
+def on_page_markdown(markdown: str, **_: Any) -> str:
+    """Expand the gallery markers (MkDocs ``on_page_markdown`` event)."""
+    if SETUP_MARKER not in markdown and not GALLERY_MARKER.search(markdown):
+        return markdown
+    gallery = _load_gallery()
+    setup = gallery.body_source(gallery.define, returns="omit")
+    markdown = markdown.replace(SETUP_MARKER, f"```python\n{setup}```")
+    return expand_markers(markdown, gallery)

{rootfig-0.2.0 → rootfig-0.2.2}/docs/plotting.md

@@ -79,7 +79,10 @@ the signal. The values are returned as a `Ratio` in `Plot.ratios`.
 
 `ratio_ylim` and
 `ratio_label` override the automatic range (at least 0.5 to 1.5, widened to
-cover the bulk of the points) and label (`Ratio to X` or `Data / MC`). The
+cover the bulk of the points) and label (`Ratio to X` or `Data / MC`). A
+rotated y label is bounded by the height of the short ratio panel, so a long
+one is shrunk and, if that is not enough, wrapped onto two lines; pass a
+shorter `ratio_label` such as `"Ratio"` to keep it at full size. The
 computed values are returned in `Plot.ratios` as
 [`Ratio`][rootfig.Ratio] objects (`values`, `errors`, `band`, `edges`).
 
@@ -134,6 +137,10 @@ computed values are returned in `Plot.ratios` as
   later renders exactly the layout that was computed, in the style's fonts.
 - `Plot.fig`, `Plot.ax`, `Plot.ratio_ax` are plain matplotlib objects;
   `Plot.histograms` wrap the `hist.Hist` objects with labels and statistics.
+- In a notebook the figure is displayed automatically — it is a pyplot figure,
+  flushed by the inline backend at the end of the cell, so `%matplotlib inline`
+  is not needed. End the call with `;` to hide the `Plot` repr, and use
+  `Plot.close()` in loops that make many figures.
 
 ## 2D histograms and correlations