docs: the glossary says a model holds no data, as math-spec uses the word, and every link into math-spec's docs resolves

[FBumann]

Prompt: classes of a loaded model ? What is "model" use for in our package? Is it consistent?

Note

The following content was generated by AI.

Later prompts that set scope: "Do it", then "Check if the specsolve PR has correct links! mathspec changed its docs a bit!"

The glossary now defines a model as math-spec does: the problem a spec states, with no data. specsolve.Model is that model with data attached. All 85 links into math-spec's docs resolve on its current site. Before this PR, 20 of the 48 distinct URLs were broken.

Method, gate output, alternatives

Glossary (docs/reference/glossary.md):

• The opening line now reads: "A spec is the model you write: the math, with no data. A Model is that model with your data attached."
• The Model entry says the word is math-spec's, and specsolve.Model is that model with data attached.
• The matching change in math-spec is docs: engine authors get a program api page rendered from math_spec.program, and the per-module pages and the file-and-program page are gone energy-models/mathspec#697.

Links. math-spec's main now holds the merged docs restructure, and #568 moved its site to zensical. I built that site locally from main with zensical and checked every math-spec.readthedocs.io URL in this repository against its pages and element ids.

• Ladder pages, 16 links: they linked examples/pypsa/#rung-N. The rungs are headed rung-N--<name>, and rungs 10 and 12–15 have a page of their own. The names differ from this ladder's (multi-link, not multilink), so they cannot be derived. tools/ladder.py now holds a CORPUS_RUNGS table from rung to page and anchor, and the 16 pages are regenerated. The regeneration changes one line per page.

• Hand-written links:

  Old target	New target
  about/limits/#solver-capability (4)	about/what-counts-as-language/#what-each-tool-decides-for-itself
  reference/language/expressions/#named-expressions (3)	reference/language/named/#expressions
  reference/language/dimensions/#relations (2), #how-the-map-is-supplied	reference/language/relations/, #the-data-contract
  reference/language/absence/#a-row-with-no-variable-terms-is-not-built	#rows-with-no-variable-terms
  reference/language/piecewise/#lp-the-one-that-declares-nothing	#method
  reference/language/reading/… (3)	reference/reading/…

  One link's text quoted the old heading, "Capability is not the ceiling". It now reads "what each tool decides for itself".

Gates (pixi is not installable in this session; a Python 3.12 venv with pip install -e . stood in):

• python -m tools.ladder --check: exit 0.
• pytest tests/test_pypsa_ladder_page.py tests/test_docs_math.py tests/test_docs_site.py tests/test_doc_examples.py: 200 passed, 73 skipped (the docs group is skipped in the default environment).
• ruff check and ruff format --check (0.16.1) on tools/ladder.py: clean.
• Link check: 85 links, 0 broken.
• Not run: pixi run check, the full suite, the docs build.

Not done:

• specsolve.Model is not renamed.
• The CORPUS_RUNGS table breaks again if math-spec renames a rung heading. A test that asks math-spec's built site would catch that, but this PR does not add one.

🤖 Generated with Claude Code

https://claude.ai/code/session_01A89tReSh8rTBG9ocy7688y

[codspeed]

Merging this PR will not alter performance

✅ 24 untouched benchmarks
⏩ 82 skipped benchmarks¹

---

_{Comparing claude/docs-review-glossary-fbheb3 (32c551a) with main (8c783ca)²}

Footnotes

1. 82 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

2. No successful run was found on main (c6ffe74) during the generation of this report, so 8c783ca was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[read-the-docs-community]

Documentation build overview

📚 lpspec | 🛠️ Build #34753410 | 📁 Comparing 356d3d2 against latest (210e96f)

  🔍 Preview build  

1 file changed

± reference/glossary/index.html

[read-the-docs-community]

Documentation build overview

📚 specsolve | 🛠️ Build #34753411 | 📁 Comparing 356d3d2 against latest (210e96f)

  🔍 Preview build  

1 file changed

± reference/glossary/index.html