docs: the readme drops the internals diagram and the repeated formats, and is a third shorter - #699
Merged
Merged
Conversation
…, and is a third shorter The README folds only the whole document with its symbol table. The LaTeX and Typst folds, the mermaid diagram, the second intro paragraph, the Spec and Program sentence, the diff benefit and the issue-number note are gone, and the licence section is two lines. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Q8Y8AoPsJCyMsURHvgzm7h
FBumann
added this pull request to stack #684
September 25, 2026 07:09
…line comments Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Q8Y8AoPsJCyMsURHvgzm7h
…saying what is published Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Q8Y8AoPsJCyMsURHvgzm7h
…to docs/readme-cuts
…to docs/readme-cuts # Conflicts: # README.md
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Q8Y8AoPsJCyMsURHvgzm7h
…to docs/readme-cuts # Conflicts: # README.md # docs/static/extras.css
…to docs/readme-cuts # Conflicts: # README.md
FBumann
added a commit
to fluxopt/specsolve
that referenced
this pull request
Sep 25, 2026
…tem modellers, in cards with icons, and the readme is under half its length (#1743) > **Prompt:** Look at mathspecs readme and docs homepage. specsolve should follow its example. Be leaner, show the selling points, use icons etc. Check the prompts used in the docs prs on mathspec > [!NOTE] > The following content was generated by AI. Later prompts set the four benefits: - "I think the big selling points are: tables in, tables out… model topology (sparsity) does not affect performance, built in decomposition (rolling horizon, scenario sweeps, myopic?), validated against pypsa in terms of numbers AND capabilities, takes the burden of making the model building performant off of the user. Minimalistic api… Archivable" - "The minimal api fits 2… the solver keep feature in rolling etc should be in 2… 2 and 3 should maybe be swapped" Later prompts also set the tagline ("Keep the native solver connected for warmstarts, quick updates… Stay brief!") and the link targets ("Are there better targets for each box?", then "Yes. Stacked PR for 2"). The user chose the icons from rendered option sheets. The README and home page now follow math-spec's (energy-models/mathspec#698, energy-models/mathspec#699). They show badges, a tagline, a short intro, and four benefits. On the home page each benefit is a card with an icon, and the whole card is the link. README: 1,321 → about 540 words. Home page: 1,034 → 663. Stacked on this: #1746 (sweep tutorial) → #1747 (tables tutorial) → #1748 (annotated solve block). The two tutorials repoint cards 1 and 2 to themselves. <details><summary>Method, gate output, alternatives</summary> **Tagline**, in the README and the home page hero: "Solve an optimisation model written in YAML. Attach your data as tables, and keep the solver loaded for quick updates and warm starts." `update()` keeps the solver with the model on it, and `keep='progress'` carries on from the last solve. **The four benefits** (README `benefits` snippet, which the home page includes) 1. **Tables in, tables out.** Any Arrow table (polars, pandas, DuckDB) or a parquet path goes in. Tables come out, and an archive keeps the model, its data and its results as parquet. → `howto/archiving/` (#1747 repoints it to the tables tutorial) 2. **Sweeps and rolling horizons built in.** Scenario sweeps, rolling horizons and myopic pathways run in one call, and each window is checked against how the model couples. → `reference/sweeps/` (#1746 repoints it to the sweep tutorial). The docs use "decomposition" for Benders, which `about/decomposition.md` says specsolve ships no driver for, so the card takes its reference page's name. 3. **Fast, and hard to get wrong.** A model's topology does not change its cost. The solver stays loaded: `update()` puts new numbers on it, and `keep='progress'` warm-starts from the last run. The API is a handful of verbs. → `about/benchmarks-scaling.html`, the results rather than the method page. 4. **Validated against PyPSA.** All 16 rungs match PyPSA's objective, and 12 match its duals row for row: two rungs are integer models with no duals, and rungs 12 and 14 differ on some dual rows, as their ladder pages show. → `examples/pypsa_ladder/` **What math-spec's PRs asked for, and what this takes from them** - #698 asked for the key selling points, core user benefits, clickable professional boxes, icons, and CSS. Taken here as: the benefits are a README snippet, which the home page includes inside `grid cards`; the icons come from CSS, chosen by each card's link; the whole card is the link. - #699 asked what could be cut, for the inline comments to go, and for links instead of prose. Taken here as: no internals diagram, no inline comments except the objective comment the README test reads, and links instead of repeated prose. **README** - Badges in math-spec's flat style (CI, PyPI, Python, Docs, License), as a snippet the home page includes. - The tagline, and an `intro` snippet that names math-spec as the language, names the solvers, and says the same file can build a `linopy.Model`. - The four benefits, with absolute links, because the home page includes the snippet from inside `docs/`. - The example; documentation; installation (one command, plus one sentence on the extras); prior art; status; licence. - **Removed:** - the benchmark paragraphs; the benchmarks page holds them; - the mermaid internals diagram; - the "Why" list; - the linopy code block; - the walkthrough paragraph; - the install block with inline comments. **Home page**: the six hand-written cards are gone. Their benchmark claim ("2–4x faster than linopy") had drifted from the README's "1.01x to 1.29x". The page includes the README's `badges`, `intro` and `benefits`, so the text lives once. "Where to next" is a list. **Cards** (`docs/stylesheets/extra.css`) - math-spec's card rules. `li:has(> a[href$="…"])` picks each card's icon by where its link points. - Icons in `docs/stylesheets/icons/`: - `table-arrow-right`, `speedometer` and `transmission-tower` are Material Design Icons, Apache-2.0, Pictogrammers. - `split.svg` is drawn for the sweeps card, MIT. **Also:** `docs/guide.md` linked `index.md#the-whole-thing-in-one-model`. It now links `#a-model-is-one-file`. **Gates** (pixi is not installable in this session; a Python 3.12 venv with the docs group's pins stood in): - `python -m zensical build --strict`: "No issues found". - Headless Chromium: each card's icon resolves. 25 of 25 sample points on every card resolve to its link, in light and dark. - `pytest tests/test_doc_examples.py tests/test_docs_site.py tests/test_models_gallery.py`: passed. The README example solves to 1920.0. - `ruff check .`, `ruff format --check .` (0.16.1): clean. - Not run: the full suite, `pixi run check`. **Not done:** `docs/README.md`, the docs folder index, is unchanged. </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.
Replies that set the scope: "Do it as another stack". "I think those iline comments should go too". "Also change this to be simply link to the pages etc. Well be soon on pypi..."
Note
The following content was generated by AI.
The README drops to about two thirds of its length. It keeps one folded math block, the whole document with its symbol table. The internals diagram, repeated text, the long licence, the inline comments and the install prose are gone. The four remaining home page cards sit two to a row.
Method, gate output, alternatives
Cuts
tools/home_math.pynow writes only the first fold, and the fold count intests/test_docs.pygoes from 3 to 1.docs/reference/reading.mdcovers the same ground.enginessnippet.SpecandProgramsentence after the Python block. It is for engine writers.extras.csssets a two-column grid for them on the home page.tools/home_math.pywrites.docs/howto/installation.mdstill gives the git command, and is the one page to change at the PyPI release.#698 is merged in, with a merge commit, not a rebase. The only conflict was the diff bullet, which this PR removes.
Gates. pixi is not installable in this session, so a Python 3.12 venv stood in.
pytest -q -n auto:1633 passed, 7 skipped.python -m tools.home_math --check: 2 pages current.mkdocs build --strict, with thedocs.python.orginventory removed because the proxy blocks it: exit 0. A screenshot of the built home page shows the four cards 2×2.prettier --check,typos,reuse lint,ruff check .,ruff format --check .: clean.pixi run ci,compile-tex, lefthook.Not done: the badges, the tagline, the example, the remaining benefits and Status stay as they are.
🤖 Generated with Claude Code
https://claude.ai/code/session_01Q8Y8AoPsJCyMsURHvgzm7h