docs(benchmarks): the benchmark charts and their method are one page of the docs, in the site's theme

[FBumann]

Prompt: could we include the charts etc into the regular docs? Or does it need to be a standalone html page like it it right now? — Yes merge them

Note

The following content was generated by AI.

The benchmark charts move from the standalone benchmarks-scaling.html into about/benchmarks.md. That page now also holds the method, so there is one "Benchmarks" entry in the nav. The charts follow the site's light/dark toggle and work with instant navigation.

How the charts live inside the docs

• Import map. overrides/main.html (theme.custom_dir) adds the TanStack/d3 import map to the head of every page. It has to be every page because instant navigation never re-renders the head: a reader who reaches the benchmark page from another page keeps the first page's head. A map costs nothing until a module asks for it.
• Script. docs/javascripts/benchmarks.js is loaded through extra_javascript as type: module. On each document$ emission it destroys the previous page's charts. It then imports TanStack on demand, only when the page has a #benchmark-charts block, so no other page fetches the library. It stops if the reader has navigated away while the library loads.
• Page. The controls, panels, table and JSON spec are one HTML block in the Markdown. The prose around them is Markdown: a purpose line, the model list, "Reading the charts", then the method sections that were benchmarks.md.
• Theme. docs/stylesheets/benchmarks.css takes surfaces and text from the theme's --md-* variables and switches the series and table colours under [data-md-color-scheme="slate"], so the block follows the site's toggle. The standalone page only followed the operating-system setting. The panels sit two to a row in the narrower content column.
• Data. benchmarks-scaling.json is renamed benchmarks.json, after its page. bench/plot.py, the published-benchmark workflow artifact list, docs/README.md and bench/README.md follow.
• Links. The README card, the landing-page card icon selector in extra.css, the About index row and the two in-page links now point at about/benchmarks/. bench/report.py drops its link to the old chart page.

Prose

• The old chart page said "a quick cell here took 84 rounds and a slow one 9", which contradicts the method page's current "every measurement gets the same nine rounds, pinned". That sentence is dropped, and the median section now opens with the nine-round rule.
• The explanation of the length/width switch was an HTML comment on the old page. It is now a bullet in "Reading the charts".
• The About index row said the page measures "build and solve cost against linopy". It measures build cost only, against four other ways of writing the model, and now says so.
• Measured with the docs-writing script: 86 sentences, median 17 words, 18 over 25. The old method page: 54, median 17, 11 over 25.

What was verified, and what was not

• Gates: pixi run check passes on 53ad43d (4999 passed). pixi run docs-build (strict), pixi run docs-test (112) and tests/test_docs_site.py + tests/test_doc_examples.py (140) pass. The bench harness tests pass (266).
• Browser, on the built site: headless Chromium, with the jsdelivr files served from the npm tarball. Each check was run twice, once on a direct load and once after arriving by instant navigation from the About index.
  • The page draws 5 panels and 20 table rows.
  • Each toggle is asserted by its effect. Width gives 1 panel and 4 rows. Peak RSS gives axes in GB. Linear–linear gives a zero tick. Hiding pyomo in the legend removes its table column. The pressed state follows each click.
  • The dots read their computed colours. Every measured dot has a ring in the surface colour, and every projection ring is filled with the surface colour.
  • Leaving for another page leaves no charts or tooltips behind, and Back redraws them.
  • No other page fetched from jsdelivr before the benchmark page was opened.
  • Both themes follow the site scheme.
  • Console errors came only from MathJax, Mermaid, fonts and the GitHub API, whose hosts the test blocks. None came from the charts.
• Two defects shipped in earlier commits of this PR, and both came from names carried over from the standalone page.
  • Dead toggles. The click handler still matched the old .seg class. My first browser test counted panels and rows, which stay the same across the scale and metric toggles, so it missed this. e9a71bb fixes it.
  • Dots without rings, and black projection rings. The dots used --surface-1, a token that the docs stylesheet does not define. 53ad43d switches them to --surface.
  • The toggle and dot-colour checks above are the ones that would have caught these defects.
• Not checked: the real jsdelivr load, as in docs(benchmarks): the benchmark charts read a published JSON table of measurements and label our engine specsolve #1851 and docs(benchmarks): the benchmark page highlights specsolve, projects the sizes a budget refused, and compares every library with it in one table #1855.

What was not done

• No redirect from the old URL. about/benchmarks-scaling.html now returns 404, under the no-compatibility rule.
• A stale anchor left alone. bench/README.md links a #the-density-sweep-and-a-claim-it-refuses anchor that predates this PR and no longer exists. It is unchanged here.
• The label, tooltip and polish changes discussed in the session are left for a follow-up.

🤖 Generated with Claude Code

https://claude.ai/code/session_01K42KwZJtqPPhf5hDzUD91o

[read-the-docs-community]

Documentation build overview

📚 specsolve | 🛠️ Build #34979813 | 📁 Comparing 53ad43d against latest (99462fe)

  🔍 Preview build  

4 files changed

± about/index.html
± about/benchmarks/index.html
± about/changelog/index.html
- about/benchmarks-scaling.html

[codspeed]

Merging this PR will not alter performance

✅ 67 untouched benchmarks
⏩ 307 skipped benchmarks¹

---

_{Comparing claude/exciting-ritchie-ap020w (53ad43d) with main (99462fe)}

Footnotes

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