docs: the readme and home page lead with what a user gets, and name specsolve and linopy as engines - #698
Merged
Conversation
…pecsolve and linopy as engines The three design properties become five user benefits, shared with the home page as a README snippet. A new benefit links the PyPSA example pages. specsolve and linopy are named as engines, with support in both marked as work in progress. The home page's primary button is now the examples. The unused flow snippet markers are gone. 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
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Q8Y8AoPsJCyMsURHvgzm7h
… short line Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Q8Y8AoPsJCyMsURHvgzm7h
…n one follows its link Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Q8Y8AoPsJCyMsURHvgzm7h
… every tool reads one public api The icons are Octicons (MIT, GitHub Inc.) and Material Design Icons (Apache-2.0, Pictogrammers), copied from the icon sets mkdocs-material bundles, with their licence in each file's header. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Q8Y8AoPsJCyMsURHvgzm7h
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: "1. Name linopy and specsolve and link them (work in progress) … 3. Yes! We need core user benefits! Stat the list, we refine it later … 5. Yes 6. Yes. Base it off of #697". Then: "Why not keep the nice boxes?", "Clicking the box anywhere should use the link … Can we keep it more professional?", "Id like icons … 1D, 2A, 3E, 4A. I think 3 should maybe not only be about an engine. The whole architecture is about mathspec being a self contained thing with clear api. Also analyzers etc can use it." and "And do CSS".
Note
The following content was generated by AI.
The README and the home page now open with five user benefits instead of three design properties. On the home page each benefit is a card with an icon, and the whole card is a link. Both pages name specsolve and linopy as engines (work in progress), and Examples is the primary button.
Method, gate output, alternatives
Changes
enginesnames specsolve and linopy. It says that support in both is work in progress.benefitsreplaces the three properties with five bullets. Each bullet has a bold headline, one sentence and a "→" link. The five are:docs/index.mdgets a "What it is for" section. It includes thebenefitssnippet inside<div class="grid cards">, then theenginessnippet.docs/static/extras.cssstyles the home page cards only:::aftercovers the card, so the whole card is the click target::beforedraws the icon as a CSS mask in the accent colourli:has(> a[href$="…"]), by where the card's link points, so reordering the README list cannot move an icon onto another carddocs/static/icons/. They are copied from the icon sets that mkdocs-material bundles:checklist.svg: Octiconschecklist-24, MIT, GitHub Inc.sigma.svg,puzzle.svg,transmission-tower.svg: Material Design Icons, Apache-2.0, Pictogrammers.LICENSES/Apache-2.0.txtis added for REUSE.flowsnippet markers are removed.Why CSS rather than card markup. The README holds the only copy of the text, and GitHub cannot render Material card or icon markup.
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.reuse lint: compliant, 254 of 254 files.mkdocs build --strict, with thedocs.python.orginventory removed because the proxy blocks it: exit 0.elementFromPointat a card's corner resolves to its link.prettier --check,typos: clean.pixi run ci,compile-tex, lefthook.:has()needs Firefox 121 or later, Chrome 105 or later, or Safari 15.4 or later. An older browser shows the cards without icons.Deliberately not done
docs/contributing.mdstill says "The module pages under Development are generated from the docstrings". This is stale after 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.🤖 Generated with Claude Code
https://claude.ai/code/session_01Q8Y8AoPsJCyMsURHvgzm7h