docs: the readme and home page lead with four benefits for energy system modellers, in cards with icons, and the readme is under half its length

[FBumann]

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.

Method, gate output, alternatives

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/ (docs: a tutorial feeds the dispatch model from parquet, reads the answer as tables and queries its archive #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/ (docs: a tutorial solves one model once per scenario and then window by window #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

• A dense bound's label order is paid per use, not once at bind #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.
• The ladder never varies declaration count within a case #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.

🤖 Generated with Claude Code

https://claude.ai/code/session_01A89tReSh8rTBG9ocy7688y

[codspeed]

Merging this PR will not alter performance

✅ 24 untouched benchmarks
⏩ 82 skipped benchmarks¹

---

_{Comparing claude/docs-readme-homepage (5303eeb) 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 (53c3910) 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. ↩

[read-the-docs-community]

Documentation build overview

📚 specsolve | 🛠️ Build #34755444 | 📁 Comparing 5303eeb against latest (6fd6513)

  🔍 Preview build  

2 files changed

± index.html
± about/changelog/index.html

[read-the-docs-community]

Documentation build overview

📚 lpspec | 🛠️ Build #34755244 | 📁 Comparing 0ab06d4 against latest (6fd6513)

  🔍 Preview build  

2 files changed

± index.html
± about/changelog/index.html