docs: an Examples section, each model beside the math it prints - #38
Merged
Merged
Conversation
The site surfaced examples only as rendered math and never as models. The homepage prints `examples/dispatch.yaml`; `operators.md` prints one equation per probe as table cells. A reader could see the equation `sum(by=)` renders as and never see a file that declares one, which is the wrong way round for a language whose pitch is that the file and the math are the same thing. There was no Examples entry in the nav at all. `docs/examples/` is three pages: an index, the dispatch model, and the probes as a group. Each carries hand-written prose about what its model is for, and a generated block — the file verbatim, then the document the typesetter prints from it. `tools/gallery.py` writes those blocks and `tests/test_docs.py` compares the committed pages to it, so math typed into a page is not a claim nothing checks. That is the `test_the_gallery_math_is_current` the markdown format's docstring has been naming all along. The probe page reuses `spec_math.OPERATORS`, which is what keeps it and the operator table naming the same models. Prettier pads the legend tables the renderer emits and the generator writes them unpadded, so each undid the other and the committed file could satisfy neither. The two generated pages join CHANGELOG.md in `.prettierignore`, under the same rule: the generator wins where nobody edits by hand. `index.md` carries no generated block and is not listed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ADtfZf4V6W9XcLRSwSgHzE
FBumann
force-pushed
the
claude/examples-gallery
branch
from
August 22, 2026 21:08
ef6c1f8 to
3f5474d
Compare
FBumann
marked this pull request as ready for review
August 23, 2026 06:14
FBumann
added a commit
that referenced
this pull request
Sep 10, 2026
…442) * Add simpler language requirement to coding agent guide * docs: the pages read in plain English rather than dense shorthand Rewrite every Markdown page that earlier commits wrote with Claude, in Simplified Technical English: short sentences, one idea each, active voice, and no em-dash asides carrying a second clause. The meaning of each page is unchanged. Scope is the 28 Markdown files where blame attributes 80% or more of the lines to a commit co-authored by Claude. Generated regions are untouched: each edit stays outside the gallery, notation, operator-math and home-math markers, and `pixi run ci` passes, so no generated page drifted. AGENTS.md is in that set, so its own rules are rewritten too. Its Language section now also names the Markdown pages in this repository, which the earlier wording left to issues, PRs and commit messages. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * docs: the pages read as a reference rather than as an essay The pages argued a case where a reader came to look something up. A bold claim opened a paragraph, a heading named a theme instead of a question, and a closing clause graded the language rather than saying anything. AGENTS.md now holds the prose rules, in `## Prose`, which replaces `## Language`. It gives the register, the words to avoid, and the three parts of a reference entry. Applied across the tree: - 91 bold claims become plain sentences. The 15 that stay mark a term where a page defines it. - 18 headings name what their section answers. - `ceiling` becomes `limit`, because `ceiling` already names the operator that rounds up. `verb` becomes `function`, `sayable` becomes allowed, written or "the language cannot express it", and a restriction no longer lifts. `docs/about/ceiling.md` and `what-counts-as-a-verb.md` move with those names, and `degree.py` names the new path in the message it prints. - Eight traps become admonitions, where a reader who skims gets a silently wrong model rather than an error. Verified with `pixi run ci`: lint, 1152 tests, `mkdocs build --strict`, and 28 compiled TeX documents. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * docs: the pages define the words they use rather than assuming them Every word this project owns is now defined where a page first uses it: consumer, sink, backend, primitive, macro, formulation, `escape:`, label budget, frame, bounded-halo and rung. `limits.md` opens with what a model can say and who should read the page, and it names the `escape:` block before it argues about one. Words with no home anywhere — the closure, the plan, streamability, a lane, COO, an island, an axis — are replaced by what they stood for, and three `hard rule N` references that pointed at a list outside this repository now state their content. AGENTS.md carries the rules this pass needed and did not have: define a project word at first use, say what happens rather than what kind of thing something is, do not describe the page, and bold what the reader must not miss. That last one replaces a rule that banned emphasis on a short phrase, which had cost `**exactly one**` and its like. README.md and docs/index.md were regenerated after the prose above them changed, and `examples/pypsa_quadratic.yaml` carries its own description. pixi run ci passes: lint, 1152 tests, the strict docs build, and 28 compiled LaTeX documents. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * docs: the pages read as a concise reference and no longer contradict one another Every hand-written page is rewritten to the prose rules in AGENTS.md: the fact first, one thought per sentence, project words defined at first use, no metaphor and no grading of the language. The hand-written prose is about a third shorter. Generated blocks are untouched and current. Contradictions between pages are resolved to one answer each: - The closed operator set is `sum`, `sum_back`, `at`, `shift`, and `dual` in a reported expression, on every page that lists it. - Rule 9 said a named expression never takes degree 2; the expressions and reported pages said it is held to the limit of the place that reads it. The rule now says the latter. - Rule 8 counted two positions where a missing value is refused; the absence page counts four. The rule now defers to the page. - The errors table refused `**` outright; the expressions page admits it over variable-free operands. The table now says so. - `escape:` was advertised as existing on the home page and README, and as unshipped on the errors page. Every mention now says it is #38 and unshipped. - The limits page said a schema merge (#30) and qualified names (#29) were coming, then that both were closed. Only the closure remains. The functions page no longer cites `merge` and `coverage:`, which do not exist. - Consumer-only names (`result.objective`, `diagnostics().omissions`, HiGHS, lpspec's query fragments) are no longer described as this package's. - The reading page carries main's `footprint.domains`, `where_children()` and `to_yaml()` sections, and the declarations page main's backtick rule. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs: every sentence names who does what, with the example beside it The previous pass produced short sentences whose subjects were "the question", "the rule" and "the answer", and a reader who had not written the language could not picture any of them. AGENTS.md gains a "Concrete before abstract" section, ahead of the sentence rules: the subject of a sentence is a person, a program or the file; every general statement is followed by its instance or replaced by it; write the common word; and ask whether the reader could draw the sentence. The three about/ pages and the ten rules are rewritten to it. "Consumer" is replaced by the engine, renderer or checker that is meant, everywhere except where a page defines the term. Every abstract paragraph on the reference pages gains its example: the engine that reads `spec.constraints` and builds a model with a variable missing; `load` with 8760 snapshots against `price` with 8759; HiGHS rewriting a set that Gurobi takes as one. Verified with `pixi run lint`, the docs tests, the strict docs build and all four generators' `--check`. The full suite and `compile-tex` were not rerun for this prose-only change. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs: the page on the public API is named for the API rather than for functions "What counts as a function" read as a page about `sum` and `shift`. The page is about which functions `math_spec` exports, and its first sentence now says so and points the operator question at the limits. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs: the public API test says what it checks, with to_spec as the example Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs: a new feature is a new key in the file, shown against the Python call it is not Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs: software that reads a model is a tool, so that Program names only the object to_program returns "Program" meant three things across the pages: the software reading a file, the `Program` object, and a linear program. The software is now a tool, and the AGENTS.md words table says why. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs: an unshipped block is a planned issue, not one of the kinds a construct can be `escape:` had a bullet beside macro, primitive and formulation, and a row in the words table, while no such key exists. It is now one sentence under the refusal it would answer, pointing at #38. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs: the advice section is a table of the two warnings rather than four paragraphs Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs: the README opens with what you do with a file rather than with what the package contains Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * More verbose variable/param names in readme * docs: every sentence has a subject and a verb, and a heading names its subject (#445) Three shapes flagged on #442, removed where they appear and written into the docs-writing skill so they do not come back. A paragraph no longer opens on a title-like fragment. "Grammar first, which is usually free because `f(x, k=v)` already parses" becomes "Start with the grammar, which is usually free". A heading already labels the section, so a label under it says nothing twice. A colon or a dash no longer stands in for a verb. The four catalogue entries on the examples index were noun phrases after a colon, and two example pages opened on one. Each now says who does what. Nine headings named a subject instead of narrating one. "What a solver can take is a separate question" becomes "Solver capability", and "An unknown key is refused" becomes "Unknown keys". Every anchor that moved is retargeted, and the strict docs build checks that. Skill sections 4 and 7 carry the three rules, with the flagged sentences as their examples. Claude-Session: https://claude.ai/code/session_01TSDYLa4NXcw2PA4cfZ1287 Co-authored-by: Claude <noreply@anthropic.com> --------- Co-authored-by: Bryn Pickering <17178478+brynpickering@users.noreply.github.com> Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-authored-by: Fabian <fab.hof@gmx.de>
FBumann
added
the
docs
Claude
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.
Base is
main— this depends on nothing else in flight. #31 → #33 → #36 → #37 now stack on top of it, and #36 adds the fourth page (commitment.md) alongside the model it shows.The gap
The site surfaced examples only as rendered math, never as models:
examples/dispatch.yamltools/home_math.pyexamples/operators/*.yamloperators.mdSo a reader could see the equation
sum(by=)renders as and never see a file that declares one — the wrong way round for a language whose pitch is that the file and the math are the same thing. There was no Examples entry in the nav at all.What this adds
docs/examples/, as a top-level nav section:Each page is hand-written prose about what its model is for, plus a generated block: the file verbatim, then the document the typesetter prints from it.
tools/gallery.pywrites the blocks,--checkreports drift, andtests/test_docs.pycompares the committed pages to the generator byte for byte — so math typed into a page is not a claim nothing checks. That test is thetest_the_gallery_math_is_currentthattypeset/markdown.py's docstring has been naming all along, anddocs/examples/is the directory it has been naming with it.The probe page reuses
spec_math.OPERATORS, which is what keeps it and the operator table naming the same models;operators.mdlinks across to it.Prettier
Prettier pads the legend tables the renderer emits; the generator writes them unpadded. Each undid the other, so the committed file could satisfy neither. The two generated pages join
CHANGELOG.mdin.prettierignoreunder the rule already written there — the generator wins where nobody edits by hand.index.mdcarries no generated block and is not listed.Checks
ruffformat and check clean,pyrefly0 errors,reuse lintcompliant,typosclean, prettier clean, 348 passed.mkdocs build --strictbuilds clean, which is what validates the new nav entries and the cross-links — run here with the intersphinx inventory fetch removed, since this sandbox's proxy blocksdocs.python.org; CI fetches it.Generated by Claude Code