fix(language): the docs gain a tutorial, a glossary and a Python API page, lose a third of the words a model writer reads, and say data is attached rather than bound

[FBumann]

Prompt: Can you do one PR for me to look at instead of a 10-stack? But keep the stack intact

Note

The following content was generated by AI.

What this changes

This PR shows the stack as one diff against main, frozen at ffcd68e. It has the same content as the head of #696. The stack has moved on since: #697 sits on top, and this PR does not get it. Merge either this PR or the stack, not both.

What this contains, bottom to top

1. docs: a glossary defines each word the docs use in a fixed sense #675 A glossary, later cut to the words no reference page owns, plus a table of words with two senses.
2. fix(language): an unknown operator's refusal points at the limits page instead of an escape key that does not exist #676 An unknown operator's refusal points at docs/about/limits.md instead of an escape: key that does not exist. The curve-by-hand how-to writes sos: {along: …}.
3. docs: what spec.expand() returns is stated once, as a different model that binds the same data #677 spec.expand() is described once, not in contradicting copies.
4. docs: a development section holds the PyPSA parity pages and the contributing guide #678 A Development section in the nav.
5. docs: one Python API page documents every public name, including the typesetting functions #679 One Python API page for every name in math_spec.__all__, in Reference beside "Typeset the math".
6. docs: a first tutorial writes the dispatch model one block at a time, checks it and prints it #680 A first tutorial, built from dispatch.yaml.
7. docs: the notation page heads each section with the construct it shows #682 The notation page is headed by construct.
8. docs: the nav keeps tutorials, how-to guides, reference and about for model writers, and puts the rest under development #683 The nav: Home, Tutorials, How-to guides, Reference, About for model writers. Development holds Building on math-spec, Contributing, and Proofs of concept.
9. docs: each page keeps only what its reader needs, and a fact stated twice keeps one home #686 The cut. The model-writer sections go from 35,678 to about 24,200 words.
10. fix(language): messages and docs say data is attached rather than bound, so a bound is only a variable's limit #694 Data is "attached", never "bound", so "bound" means only a variable's limit.
11. docs: what spec.expand() returns is documented on the model writer's python api page, and reading.md keeps only which program an engine reads #696 The Spec.expand docstring, on the model-writer API page, is the home for the call. This was first a commit inside docs: each page keeps only what its reader needs, and a fact stated twice keeps one home #686. docs: each page keeps only what its reader needs, and a fact stated twice keeps one home #686 now reverts it, and docs: what spec.expand() returns is documented on the model writer's python api page, and reading.md keeps only which program an engine reads #696 re-applies it, so the content here is unchanged.

Not in this PR: #697 (a Program API page for engine authors, no per-module pages, and file-and-program.md folded into reading.md).

Totals and gates at ffcd68e

• Docs and README, words: 60,741 on main → 57,083.
• Contains main, feat(language): a bound is null where it is open, never infinite, in the file and in the program #689 included. The one conflict, in declarations.md, keeps the "a bound is never infinite" rule. The quoted advice message on errors.md and check.md now reads "bounds.lower is open", which is what advice prints since feat(language): a bound is null where it is open, never infinite, in the file and in the program #689.
• Gates (pixi is not installable in this session; a Python 3.12 venv stood in):
  • pytest -q: 1632 passed, 7 skipped.
  • ruff: clean.
  • mkdocs build --strict, with the blocked docs.python.org inventory removed: built, no warnings.
  • reuse lint: compliant.
  • Every generator re-run: no diff.
  • Not run: pixi run ci, compile-tex.

Why

One diff is easier to review than eleven.

🤖 Generated with Claude Code

https://claude.ai/code/session_01A89tReSh8rTBG9ocy7688y

[read-the-docs-community]

Documentation build overview

📚 math-spec | 🛠️ Build #34753041 | 📁 Comparing ffcd68e against latest (6d5ab58)

  🔍 Preview build  

39 files changed · + 3 added · ± 36 modified

+ Added

• first-model/index.html
• reference/api/index.html
• reference/glossary/index.html

± Modified

• index.html
• contributing/index.html
• examples/index.html
• about/file-and-program/index.html
• about/limits/index.html
• about/what-counts-as-language/index.html
• about/what-counts-as-public-api/index.html
• examples/pypsa/index.html
• howto/check/index.html
• howto/curve-by-hand/index.html
• and 26 more...