fix: the notation page is generated again, and something says so

[FBumann]

Targets main directly. Nothing here depends on #31 — it was stacked only because both touch docs/reference/notation.md, and that file is generated, so the overlap is a regeneration rather than a merge. Landing it first is what lets CI check #31's and #33's pages instead of a person doing it.

What this changes

tools/notation.py could not run in this repository. Its PIECEWISE map names four models that stayed behind in fluxopt/lpspec when the language was extracted (#17), so _curves() raised FileNotFoundError and the only way to touch the page was by hand — which is how a generated page ends up showing math no model here produces.

Nothing caught it because nothing ran the tool. --check has never been called by a test or a workflow, here or in the repository this came from, and the guard the docstring claims — tests/test_docs_site.py — does not exist here at all. So the page has been drifting since the extraction with nothing able to say so.

The four models come back. examples/piecewise.yaml, examples/sos.yaml, examples/piecewise_lp.yaml, examples/ports/transport_pwl.yaml — one per method:, each given the licence header this repository's examples carry (upstream's have none). They load and render against this language unchanged, and the page they regenerate is byte-identical to the curve rows already committed. So what they restore is the ability to check the page, not the page.

The page is prettier-ignored, the rule docs/examples/ already follows for exactly this reason: the generator writes unpadded legend tables, prettier pads them, and each undoes the other, so the committed file could never satisfy both. docs/reference/notation.md was not on that list, so every regeneration since has been padded back by the hook and the generator's output has never been what the file holds — which is why nothing could compare them. The whole page diff here is that unpadding, plus the two blank lines around the markers; no rendered math changes.

Two guards, in tests/test_docs.py beside the one docs/examples/ already has:

test_the_notation_page_is_current	the page equals rendered_page(), byte for byte
test_every_piecewise_method_has_a_model_on_the_notation_page	PIECEWISE covers PIECEWISE_METHODS — the claim the docstring makes about it

Also stale, in the same docstring

Four methods, not three, and a section showing one of them is a quarter of the construct rather than a third. lp arrived and the sentence counting them did not move.

What this does not do

The .inf-dropped-on-model_dump round-trip is still the reason the curves come from four real models rather than from the fixture — untouched here, and the docstring's account of it stands. Fixing it would let the fixture carry a curve and retire PIECEWISE altogether, which is a change to the model layer, not to a docs tool.

What it means for the open PRs

#31's committed page is the prettier-padded shape, so once this guard is on main that PR is red until its page is regenerated — which is the point of the guard, and a defect that was otherwise invisible. #31 and #33 both need rebasing onto the new main; #31's one conflict is the generated page, resolved by running the tool, and #33 does not touch it.

Checks

pixi.sh is unreachable from this environment, so the gates ran on a 3.13 venv at the versions pixi.toml pins, plus prettier@3.9.3 and typos fetched directly: 350 passed on this base (348 plus the two new guards), ruff check and format clean, pyrefly 0 errors, prettier clean, typos clean, reuse lint compliant.

Two things worth naming rather than implying:

• The prettier-ignore entry was checked to be load-bearing, not decorative: prettier --check --ignore-path /dev/null docs/reference/notation.md reports the page as needing reformatting, and with the entry it is left alone.
• tools/render_tex.py globs examples/**/*.yaml, so the LaTeX gate now covers nineteen models rather than fifteen. The render half runs clean here; the compile half needs tectonic, which this environment has no way to run — CI is the first place that executes it. The four models come from a repository running the same two-package gate, so they compiled there.

[read-the-docs-community]

Documentation build overview

📚 math-spec | 🛠️ Build #34191410 | 📁 Comparing 931d173 against latest (05c7219)

  🔍 Preview build  

1 file changed

± reference/notation/index.html