feat!: a spec written back out and its typeset document follow one section order

[FBumann]

Prompt: Lets rearrange the blocks in SPec, as a stacked PR 818. […] I think piecewise and sos should move below constraints. first sos, then piecewise. Im not sure about macros, probably right above expressions?

Follow-up: What order would you suggest? — Is this a good fit? WHat does tyesetting do? — Yes! — 818 was merged! 848 needs to target main directly — Lets challenge the order of the typesetting too! We should probably decide the ordering of both simulatniously...? And keep the data contract in mind (what names are provided as data by the user...? Those hsould be high up...) — I like most of it. But assumptions are also kind of second class citizens for me... — Make the description carry this order and the reasons. As a small table

Note

The following content was generated by AI.

Breaking. The file and the typeset document now use one section order. Canonical files that have objective, sos, piecewise or macros change.

Part	File	Document	Why here
Given	given	Given	A reader sees first what the file reads and does not build (#818). Its obvious this is a fragment.
Data	dimensions, relations, parameters	Sets, Parameters	The data contract: the names the user gives as data stand high.
Decisions	variables	Variables	What the solver chooses, before the rules about it.
Problem	objective, constraints, sos, piecewise	Objective, Subject to (constraints, sets, curves), Variable domains	The textbook statement, "min … subject to …". A solver holds a set and a curve as constraints.
Helpers	macros, expressions, masks	Definitions, Masks	The "where" after the problem. Names resolve at load, so a use may come first.
Assumptions	assumptions	Assumptions	A check on the data, not part of the problem.

Each part of the document keeps the file's order. The one exception is Variable domains: it reads variables but prints after the rows.

Method, gate output, alternatives

File.

• src/mathspec/spec.py: the fields on Spec move. objective goes before constraints. sos and piecewise go directly after constraints. macros goes directly before expressions.
• tests/test_canonical.py: SECTIONS pins the new order. With spec.py as on main, test_the_sections_come_in_one_order fails for 27 example specs (27 failed, 26 passed). With the move, 53 pass.
• docs/reference/language/file.md and docs/reference/reading.md: the key table and the order list follow. reading.md did not list masks before; it does now.

Typeset document.

• typesetting/legend.py: Given moves from after Variables to the top of the legend.
• typesetting/walk.py: Variable domains moves from after Masks to directly after Subject to. A sos: set moves from under its variable in Variable domains to Subject to, between the constraints and the curves.
• tools/gallery.py: a declared page (docs/examples/pypsa.md) prints the domains after the constraints, before the named expressions.
• tools/notation.py: the caption of the SOS section says where a set prints now.
• docs/reference/typeset.md: one bullet states the order of the legend and the equations.
• docs/several-files.md: the two hand-kept outputs move Variable domains before Definitions. tests/test_several_files_page.py runs the steps and holds the page to what they print.
• tests/typesetting/test_cases.py: test_the_definitions_print_in_declaration_order read the Definitions section up to Variable domains. Definitions is now the last section in that fixture, so it reads to the end.
• Regenerated: the three golden files, every gallery page, notation.md, see-an-expansion.md, composed.md. With walk.py and legend.py as on main, 36 tests in tests/typesetting, tests/test_docs.py and tests/test_several_files_page.py fail. With the change, they pass.

Gates. pixi run lint: clean. pixi run test: 2841 passed, 1 skipped. I did not run docs-build or compile-tex. CI runs both.

Choices.

• The document keeps its two parts, the legend and then the equations. A document that sets each part's table beside its equations matches the table above more closely, but it rewrites the layout.
• given: parameters is data the user gives, but it still prints under Given and not under Parameters.

Alternatives not taken.

• Declare before use (macros, masks and expressions before constraints). Names are one namespace resolved at load, and the document prints definitions after their uses.
• assumptions directly after parameters, with the rest of the data contract. It is a check on the data, not data, so it stays last.

Not done. The YAML files in docs/ and examples/ keep their written order. The loader accepts any order, and no gate checks the examples for canonical form.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LXkcLcoxVyLvgDfZgt2eUt

[read-the-docs-community]

Documentation build overview

📚 mathspec | 🛠️ Build #34970242 | 📁 Comparing 0d37ff7 against latest (6501940)

  🔍 Preview build  

53 files changed · + 1 added · ± 52 modified

+ Added

• reference/spec/index.html

± Modified

• changelog/index.html
• several-files/index.html
• about/limits/index.html
• about/relations-as-linear-maps/index.html
• about/what-counts-as-public-api/index.html
• examples/commitment/index.html
• examples/pypsa/index.html
• howto/compose/index.html
• howto/see-an-expansion/index.html
• reference/api/index.html
• and 42 more...