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 - #697
Merged
FBumann merged 2 commits intoSep 25, 2026
Conversation
…rogram, and the per-module pages and the file-and-program page are gone Building on math-spec now holds reading.md, a Program API page that renders every name math_spec.program exports, and what counts as language. The why and the tool table from file-and-program.md move into reading.md's opening, and the page is deleted. docs/static/hooks.py no longer generates one page per module: an internal module is read in the source. The docs-writing skill and the nav comment say so. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A89tReSh8rTBG9ocy7688y
FBumann
added this pull request to stack #684
September 25, 2026 06:53
…the python objects are named spec and program "Reading a loaded model" is now "Reading a spec and its program", in the title, the nav and every link. The API page says math_spec.program holds the classes a Program is made of. The glossary opens with a Model entry: the problem a file states, which holds no data. The README and the typeset docstring name Spec and Program where they said the model or a loaded model. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A89tReSh8rTBG9ocy7688y
FBumann
added a commit
to fluxopt/specsolve
that referenced
this pull request
Sep 25, 2026
…word, and every link into math-spec's docs resolves (#1740) > **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. <details><summary>Method, gate output, alternatives</summary> **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 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. </details> 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01A89tReSh8rTBG9ocy7688y --------- Co-authored-by: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Note
The following content was generated by AI.
Later prompts that set scope: "Dont fold it into the big PR. Put it into the stack!", then "classes of a loaded model ? What is "model" use for in our package? Is it consistent?" and "Do it".
What this changes
Building on math-spec is the program side only. It holds
reading.md, a new Program API page rendered frommath_spec.program, and what counts as language. The per-module pages are gone, and so isfile-and-program.md. "Model" now means only the problem a file states, and the Python objects are calledSpecandProgram.Method, gate output, alternatives
math_spec.__all__for model writers.docs/reference/program.md) rendersmath_spec.programfor engine authors. It renders all 75 names inmath_spec.program.__all__, and no name outside it.reading.mdopens with the table of which tool reads which object, and with two sentences of why.docs/about/file-and-program.mdis deleted.docs/static/hooks.pyno longer generates one page per module. The changelog linking and the inline-math rewrite stay.math_spec.programholds "the classes aProgramis made of".typesetdocstring says "aSpecor aProgram" where it said "a loaded model".pytest -q:1632 passed, 7 skipped.mkdocs build --strict, with the blockeddocs.python.orginventory removed: built, no warnings.ruff check .,ruff format --check .: clean.prettier --check,typos: clean.reuse lint: compliant.pixi run ci,compile-tex.what-counts-as-language.mdstays under Building on math-spec.math_spec.modelkeeps its name. It holdsSpecand the schema blocks, and only the source shows it.ffcd68e.Why
Engine authors need the program's contract, which the docstrings state, not a page per internal module. "A loaded model" named neither object a tool gets.
🤖 Generated with Claude Code
https://claude.ai/code/session_01A89tReSh8rTBG9ocy7688y