docs: the Python API page renders every public name from its docstring

[FBumann]

Prompt: Use the docstrings. What is api.md then for anymore?

After "Do it", on the plan to render the docstrings first and move api.md's tasks into how-tos next. Later: "How can we ensure future code changes use this format for links?", answered by a test for every docstring link and a rule in AGENTS.md.

Note

The following content was generated by AI.

docs/reference/api.md now renders all 27 exported names from their docstrings with mkdocstrings, plus the four row and frame types a caller reads back. The 483 Sphinx roles in src/ are now links, and a test holds every docstring link in src/ to landing on a specsolve object, rendered or not.

What changed, what the build caught, guards, gates, not done

The page

• A ## Reference section, grouped as the architecture's surface is: run a spec (check, build, solve, write, evaluate); run it many times (solve_over, EachCoordinate, EachWindow); what comes back (Model, Result, Sweep, and Diagnostics, Record, Metrics, SliceMetrics, which readers return but __all__ does not name); carry an answer (the two archives and six readers); errors and warnings.
• It replaces "The verbs" table and "Errors and warnings". No page linked to either.
• The task sections stay as they are, from "The spec argument" through "Choosing a solver". About 30 links on other pages point into them. Moving them to how-to guides is the stacked follow-up.

The tooling

• The docs group adds mkdocstrings==1.0.6, mkdocstrings-python==2.0.9 and griffe-sphinx==0.3.0, pinned exactly like the rest of the group. uv.lock is relocked.
• griffe-sphinx reads the #: attribute comments the tree already uses (AGENTS.md names them). Without it, the fields of Sweep, Diagnostics, Record, Metrics and SliceMetrics render with no text.
• load_external_modules: true renders SpecsolveError, LanguageError, SchemaError and DimensionError, which specsolve re-exports from mathspec, from mathspec's installed source.

The roles. All 483 Sphinx roles in src/ are converted, as energy-models/mathspec#720 did:

• A specsolve target becomes [`name`][], or [`name`][dotted.path] where it was written ~dotted.path. It resolves in the docstring's own scope.
• A name from another package becomes plain code, because the site loads no object inventories.

Keeping future links in this form

• tests/test_docs_site.py::test_no_docstring_links_with_a_sphinx_role refuses a Sphinx role anywhere in src/. It runs in the main suite.
• tests/test_docstring_links.py (new) loads src/ with griffe and the same griffe_sphinx extension the site uses. It resolves each link the way the site does: in the docstring's scope, walking outward. It refuses one that lands nowhere, or on another package. It reads 440 links, docstrings and #: comments together, and asserts it read over 400, so a walk that reaches nothing fails too. It runs under pixi run docs-test, which CI's docs job already calls, and skips where griffe is absent.
• It found 8 links in modules the site never renders that pointed at nothing. _entries no longer exists (now [_splice][]); placed is Grouping's, not _Order's; row_major, spanned, PolarsCompiler.expression and Assembly._build_objective needed their full path. A local function and mathspec's Program became plain code.
• AGENTS.md, Docstrings: a name is linked as [`name`][] where the module imports it and [`name`][dotted.path] where it does not; a name from another package is plain code.

What the strict build caught, and the fixes

• Nine links to objects the page does not render. Four are now rendered (Diagnostics, Record, Metrics, SliceMetrics). A private method, the KEEPS constant, concurrent.futures.Executor, LanguageError inside errors.py, and two internal digests are now plain code. The keep= docstrings now name the three values instead of pointing at KEEPS.
• An indented line in Model's docstring rendered as a code block with the backticks showing; it is now one line of code spans.
• A page mkdocstrings cannot render is dropped silently. zensical printed no error. The only symptom was 72 "page does not exist" warnings from inbound links. That is how the missing load_external_modules showed up. The strict build still fails, but the message points at the links, not at the cause.

Guards. Mutation table, taken by hand because tools/mutate.py mutates Python only. Each run started from a committed tree, restored through git checkout --, and dropped __pycache__ on both sides; the tree was clean after each set:

mutation	caught by	result
the ::: specsolve.check entry deleted from api.md	the entry test	caught
a :func: role added to solve's docstring	the Sphinx-role test	caught
a stale name restored ([_entries][])	the link test	caught
a link to a name that exists nowhere	the link test	caught
a link to another package ([to_spec][mathspec.to_spec])	the link test	caught

Gates, in a uv environment (dev + docs groups, gurobi and xpress extras), because pixi cannot be installed here:

• ruff check . and ruff format --check . pass.
• pytest -n auto: 4143 passed, 250 skipped, 1 xfailed.
• pyrefly check: 0 errors, on the first commit. The second commit edits docstrings and tests only.
• zensical build --strict: builds, with no issues on the first commit. The rendered page holds 130 entries, no Sphinx role, and no stray doubled backticks.
• The docs-test task's command, pytest tests/test_docs_math.py tests/test_docstring_links.py: 70 passed.

Not done:

• Moving the task sections into how-tos. That is the stacked follow-up, as agreed.
• A read of every public docstring as a caller now sees it. Only what the build and the link test flagged is fixed here.
• Hard rule 5 is unchanged. "The public interface is a declared model, not a Python API" is about constructing math, and still holds. architecture.md's surface section now says the docstrings are the reference.

🤖 Generated with Claude Code

https://claude.ai/code/session_016Pv7LzSgzt7Yn2K3ioyJXw

[read-the-docs-community]

Documentation build overview

📚 specsolve | 🛠️ Build #34762588 | 📁 Comparing 8e79d37 against latest (306921e)

  🔍 Preview build  

71 files changed · ± 71 modified

± Modified

• index.html
• about/index.html
• examples/index.html
• guide/index.html
• interactive/index.html
• lifecycle/index.html
• sweep/index.html
• tables/index.html
• about/architecture/index.html
• about/changelog/index.html
• and 61 more...

[codspeed]

Merging this PR will not alter performance

✅ 24 untouched benchmarks
⏩ 82 skipped benchmarks¹

---

_{Comparing claude/api-reference-from-docstrings (8e79d37) 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 (a8c9fbe) 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. ↩