docs: each page keeps only what its reader needs, and a fact stated twice keeps one home

[FBumann]

Prompt: The stack does add more lines to the docs than it removes. I think much of the information in the docs isnt needed or not focused enough.

Note

The following content was generated by AI.

The user's follow-up was "Yes. As one big PR stacked ontop".

What this changes

The sections for model writers (Tutorials, How-to guides, Reference, About) go from 35,678 to about 24,200 words. Rationale, history, repeated rules and engine instructions are cut. Where a fact sat on two pages, the page that owns it keeps it and the other links to it. No rule of the language changes.

Method, gate output, alternatives

Rule for every cut: a page answers one question for the reader of its section. Cuts move or delete text; none rewrites a rule.

Words per top-level section, before → after this PR: Tutorials 1,438 → 779. How-to guides 3,181 → 2,771. Reference 25,260 → 15,400. About 5,799 → 5,256, most of which is the changelog. Development 30,504 → 35,909, because it now holds the notation page.

Which page owns a fact stated twice:

• Refusals, with what to write instead: limits.md#deliberate-non-primitives.
• The degree rule: expressions.md. Reported expressions and dual: named.md.
• What a curve assumes of its breakpoints: assumptions.md.
• Groups (by=, within=): relations.md.
• Spec, Program and expand(): reading.md. 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, higher in the stack, moves the expand() call to its docstring on the model-writer API page.
• What a tool decides for itself: what-counts-as-language.md.
• Symbol tables: typeset.md.

Per area:

• Notation page: reference/notation.md moves to Development › Proofs of concept, because it renders the typesetting test model. The typeset and operators pages link the operator table instead.
• Glossary: 1,588 → 616 words. It keeps only the words no reference page owns, and the table of words with two senses.
• Tutorial: 1,419 → 767 words. Each new block is shown once, and the whole file once, folded. Every output was re-run and matches what the command prints.
• Language reference: 13,104 → 10,595 words.
  • errors.md: the refusal table becomes a link to limits.md. The error-class table now shows the real hierarchy.
  • piecewise.md and assumptions.md: the derived assumptions have one table, checked against src/math_spec/piecewise.py. It fixes a wrong claim: the decreasing-breakpoints check applies to convex and lp only.
  • operators.md: two sentences about a null relation value contradicted the data contract, and are cut.
• README, explanation pages, reading.md, typeset and how-tos: 12,310 → 9,797 words.
• Anchors removed: limits.md#solver-capability (its one inbound link was repointed), limits.md#composition-component-libraries and typeset.md#printing-what-a-formulation-states.
• Merging main (feat(language): a bound is null where it is open, never infinite, in the file and in the program #689):
  • The variables section keeps the new "a bound is never infinite" rule.
  • The quoted advice message on errors.md and check.md now says "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.
  • reading.md no longer names an infinite bound among what to_yaml leaves out.
• History on this branch: a commit that moved the expand() docs was made here and then reverted (eb3c60c). It now lands as 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, at the user's request that it be its own PR in the stack.

Gates (pixi is not installable in this session; a Python 3.12 venv stood in):

• pytest -q: 1630 passed, 7 skipped.
• mkdocs build --strict, with the blocked docs.python.org inventory removed: built, no warnings.
• ruff, reuse lint, typos, prettier --check: clean.
• Not run: pixi run ci, compile-tex.

Not done:

• The PyPSA pages are untouched, as the user asked.
• The module docstring of src/math_spec/exclusivity.py still says the case rule is stated in expressions.md; it is now in named.md.
• One commit is marked "in progress". It was pushed as a checkpoint, and later commits complete it.

Why

Much of the text was not needed by the reader of its page, or it repeated another page. The stack added more than it removed.

🤖 Generated with Claude Code

https://claude.ai/code/session_01A89tReSh8rTBG9ocy7688y

[read-the-docs-community]

Documentation build overview

📚 math-spec | 🛠️ Build #34753230 | 📁 Comparing eb3c60c against latest (9c7c0a5)

  🔍 Preview build  

36 files changed · + 3 added · ± 33 modified

+ Added

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

± Modified

• index.html
• CHANGELOG/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
• howto/check/index.html
• howto/curve-by-hand/index.html
• and 23 more...