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

[FBumann]

Prompt: .expand() is regular model writer api!

Note

The following content was generated by AI.

A later prompt set the scope: "Dont fold it into the big PR. Put it into the stack!" This change was first a commit on #686, which now reverts it.

What this changes

The Spec.expand docstring, which the Python API page in Reference renders, is now the one home for the call. reading.md, under Development, keeps only which expanded program an engine reads. The docstring no longer says "the same math".

Method, gate output, alternatives

• src/math_spec/model.py:
  • The Spec.expand docstring gives the kinds and the order they apply in, the ValueError, and that the result is a different model taking the same data. It also says the call returns itself where there is nothing to write out, and that nothing is cached.
  • The Spec class docstring says "the model with its formulations written out as plain rows", not "the same math".
  • schema/math-spec.schema.json is regenerated from these docstrings.
• docs/reference/reading.md: "Formulations written out" says which program an engine reads, and that an expansion's program holds no curve.
• Five links now point at api.md#math_spec.Spec.expand: typeset, piecewise, see-an-expansion, file-and-program, what-counts-as-public-api.
• Coverage moved: reading.md checked three claims, and they are now tests in tests/test_expand.py. The claims: the expansion is not equal to its source, expanding it again returns it, and a model with nothing to write out returns itself. The page's pinned claim count in tests/test_reading_page.py drops from 22 to 19.
• Gates (pixi is not installable in this session; a Python 3.12 venv stood in):
  • pytest -q: 1632 passed, 7 skipped.
  • ruff check ., ruff format --check .: clean.
  • mkdocs build --strict, with the blocked docs.python.org inventory removed: built, no warnings.
  • Not run: pixi run ci, compile-tex.
• This head has the same content as 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 #695's frozen head (ffcd68e).

Why

expand() is model-writer API, and its only description sat on a page for engine authors.

🤖 Generated with Claude Code

https://claude.ai/code/session_01A89tReSh8rTBG9ocy7688y

---

Generated by Claude Code

[read-the-docs-community]

Documentation build overview

📚 math-spec | 🛠️ Build #34753244 | 📁 Comparing 28fc946 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...