docs: each fact about the Python API is stated once, in the docstring of the name it belongs to

[FBumann]

Prompt: Is there even more duplication in the docs now? Especially in Reference? As a stacked PR

Note

The following content was generated by AI.

The API page is now the rendered reference plus two rules that every verb shares. Each task-section fact that no docstring held moved into the docstring of its name. The keep= guidance moved to the debugging how-to. Four drifts are fixed.

What moved where

api.md section (deleted)	Its unique facts now live in
The spec argument, Checking a spec	check: the spec shapes, "a Spec is not read again", "no verb takes a Program", the expand('piecewise') / expand() choice, and the CI-verb sentence
Checking against a sink	check: "solve and write read the same table", and a refusal names the construct and the sinks that take it. The intro of "What each sink takes"
The sources argument	build sources, which links the data contract
Building a model	Model (already covered)
Reading one row	Model.row (a label its dimension cannot hold, no reader for a column). ConstraintRow, now rendered (linopy's format, display_terms summary)
Reading a result	dual (an expanded set, duals only where a solver ran, no reduced costs or slacks). dual_ray (InfUnbdInfo / presolve, live only). Result.evaluate (an undeclared expression is not a kind, the archive model check, a new parameter is a build). to_pandas (pandas is not installed)
Writing a file	write out
Re-solving with new numbers	Model.update (a raise releases the model, the reason behind DataError, solve_over is the loop written for you)
How much of the session a solve keeps	The contract was already in Model.solve keep and Result.kept. The when-to-use guidance, the #815 numbers and #382 moved to howto/debug §6
Archiving a model, Loading or scanning	howto/archiving (already covered), Model.solve archive (sources through the build door, uncompressed), solve_over archive (a sliced source archived whole, a hand-built axis refused), SolveArchive (spec as written, digest caveats), scan_result (re-read at every collect)
Diagnostics	the Diagnostics and Metrics attributes (already covered)
Choosing a solver	Model.solve solver_name / solver_options (xpress, a time limit in three vocabularies, Gurobi environment options). solve now says "As Model.solve takes it"

Other duplicates:

• sweeps.md: "The axes" table became links to EachCoordinate and EachWindow plus the hand-built row. The SliceMetrics and "asked before it is sliced" rows point at the entries. EachWindow now states the window checks rather than naming a private method. The remote-Gurobi sentence that docs(sweeps): the sweep reference says how many sessions a sweep opens on a remote Gurobi #1771 added now links Model.solve.
• glossary: "Row types" became one-liners that link the entries.

Drifts fixed:

• solver_name omitted xpress.
• sweep.record columns were listed in three forms (6, 8 and 6). The real record has 9 columns. Sweep.record, sweeps.md and howto/parallel now say "one Record per slice", so the column list has one home.
• check's Returns said every verb takes the Program back. No verb does.
• howto/data said index levels attach by name. A MultiIndex is refused.
• The sink table said HiGHS rewrites SOS to binaries. It refuses and names Spec.expand().
• Two docstrings linked ../../docs/reference/sweeps.md, which is broken when rendered. They now use the site URL. ConstraintRow linked a private helper; that is now plain text.

Gates on the merge of #1766 (which now carries main through #1771), in a uv environment with the dev and docs groups and the gurobi and xpress extras:

• ruff check . and ruff format --check .: clean.
• pyrefly check: 0 errors.
• zensical build --strict: no issues. Every api.md#… anchor used under docs/ exists in the rendered page.
• Docs tests (test_docs_math, test_docstring_links): 70 passed.
• Full suite: 4115 passed, 250 skipped, 1 xfailed. It collects fewer tests than docs: the Python API page renders every public name from its docstring #1766 (4153) because test_doc_examples runs one test per fence, and the deleted sections held fences.

Not done: the task sections were not rewritten as new how-tos. Their examples already exist in howto/archiving, howto/debug and interactive.md. #1765 edits the api.md archive table that this PR deletes, so whichever PR merges second resolves that conflict.

🤖 Generated with Claude Code

https://claude.ai/code/session_016Pv7LzSgzt7Yn2K3ioyJXw

[codspeed]

Merging this PR will not alter performance

✅ 24 untouched benchmarks
⏩ 82 skipped benchmarks¹

---

_{Comparing claude/reference-dedup (75e9f3d) with claude/api-reference-from-docstrings (8e79d37)}

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. ↩

[read-the-docs-community]

Documentation build overview

📚 specsolve | 🛠️ Build #34762596 | 📁 Comparing 75e9f3d against latest (306921e)

  🔍 Preview build  

74 files changed · ± 74 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 64 more...