docs: readability pass — cap font, add colored terminal figures#163
Merged
Conversation
Layered on top of the task-oriented restructure (PR #161), this addresses three readability gaps in the rendered docs, none of which the restructure touched: - Font too big on wide screens. Material scales the root font to 137.5% (>=100em) then 150% (>=125em); pin it flat at 125% so body text and headings stay a comfortable size on desktop monitors. - No plots/colors. Every page but the one executed notebook was prose + a monochrome console fence, and the flamegraph the tool is built around was described but never shown. Add real, colored tool output captured as SVG: the pytest memory table (Home, Quickstart), the benchmem flamegraph summary that localises the allocation (Home, profiling), and compare --diff showing the drop (Home, compare-runs). Committed under docs/assets/ and regenerated by scripts/gen_doc_assets.py (rich export_svg over real runs; sanitised paths). - Notebook terminal output. visualize.ipynb was two plots and prose; add a colored compare --diff cell so the numbers behind the charts read in-page. scripts/gen_doc_assets.py uses --report summary, not tree — memray's tree reporter is an interactive TUI that never exits when its output is captured. mkdocs build --strict passes; ANSI colors render in the notebook output. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Documentation build overview
13 files changed ·
|
The first pass stretched every terminal SVG to the same CSS width, so a narrow capture (compare) rendered its text larger than a wide one (the memory table) — visibly inconsistent, and out of step with the body text. rich exports SVGs with only a viewBox, so the browser was free to rescale each. Bake an explicit width/height at one shared SCALE into every asset (gen_doc_assets.py), and stop forcing a common width: each figure now keeps its natural size, centered, scrolling horizontally if it's wider than the column (like a code block). Result: identical monospace text size across all three, close to the page's code font. Also: slim the memory table to one time column so it's narrower, drop the now-unneeded long title on compare --diff (removes its right-side dead space), and wrap each image in <figure class="termshot"> (md_in_html). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
FBumann
added a commit
that referenced
this pull request
Jul 20, 2026
* docs: reorganize the guides around tasks, not features The old `compare-plot.md` (425 lines) tried to be a feature tour AND a reference dump — `benchmem compare`, `--pivot`, `plot`, then a deep "Going further" tail of flamegraphs, native traces, and gating variants. A newcomer hit a wall of prose with no task to anchor on. Split it into four task-oriented guides, each answering "how do I …?": - catch-regressions.md — fail CI when memory grows (the regression hook + `--fail-on`, inline gate, GHA snippet, `--pivot` gating) - compare-runs.md — see what moved between two runs (the table, `--pivot`, `--diff`, sort/csv, sharing as md) - visualize.md — see memory as a chart (the one executed notebook: live scaling / scatter plots + the other views). Renamed from compare-plot. - profiling.md — find where the memory goes (profile → flamegraph → native traces) Nav gains a task-oriented Guides group (+ sweeps as "Compare across versions") and a separate Concepts group (metrics, dims). Only visualize stays an executed notebook — the compare/gate outputs become static blocks, so the other three pages are fast plain markdown. Retargets the docs.yaml jupytext step and mkdocs exclude to visualize.md, and repoints all inbound links at the right task page. `mkdocs build --strict` passes (no broken links). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs: point Read the Docs jupytext at visualize.md (was compare-plot.md) The RTD build config still referenced the renamed notebook source, so `jupytext --to ipynb docs/compare-plot.md` failed on the missing file. Retarget it to docs/visualize.md, matching the nav and the gh-deploy workflow. Verified by replicating RTD's exact build (the full jupytext list + `mkdocs build --strict`) locally. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs: reposition around on-demand memory profiling (find → fix) The headline promised the wrong thing. README and index led with "track memory in CI, fail a PR when the footprint grows" — but CI-gating is a newer, un-hardened feature, while the actual, battle-tested use of the tool is on-demand profiling: find what's heavy, see where the memory goes, fix it, confirm the drop. Recentre the docs on that loop: - README + index rewritten around measure → find → fix, with the memray flamegraph (the point of the tool) promoted from a buried one-liner to a top section. - Nav regrouped: a "Find & fix" section (profiling, compare) up top; the newer features (catch regressions, visualize, sweeps) demoted to a "More (newer)" section, each carrying a one-line "less battle-tested — feedback welcome" note. - profiling.md reframed as the marquee (optimize, not just detect); compare-runs.md reframed as "confirm the fix"; getting-started next-steps reordered to lead with find/fix. - Honest CI positioning: point readers at CodSpeed for continuous CI tracking, and note that since it also runs pytest-benchmark's benchmark(), the same tests serve both — no rewrite. Status note updated: the measure → profile → fix loop is the hardened core; the rest is newer. `mkdocs build --strict` passes. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs: readability pass — cap font, add colored terminal figures (#163) * docs: readability pass — cap font, add colored terminal figures Layered on top of the task-oriented restructure (PR #161), this addresses three readability gaps in the rendered docs, none of which the restructure touched: - Font too big on wide screens. Material scales the root font to 137.5% (>=100em) then 150% (>=125em); pin it flat at 125% so body text and headings stay a comfortable size on desktop monitors. - No plots/colors. Every page but the one executed notebook was prose + a monochrome console fence, and the flamegraph the tool is built around was described but never shown. Add real, colored tool output captured as SVG: the pytest memory table (Home, Quickstart), the benchmem flamegraph summary that localises the allocation (Home, profiling), and compare --diff showing the drop (Home, compare-runs). Committed under docs/assets/ and regenerated by scripts/gen_doc_assets.py (rich export_svg over real runs; sanitised paths). - Notebook terminal output. visualize.ipynb was two plots and prose; add a colored compare --diff cell so the numbers behind the charts read in-page. scripts/gen_doc_assets.py uses --report summary, not tree — memray's tree reporter is an interactive TUI that never exits when its output is captured. mkdocs build --strict passes; ANSI colors render in the notebook output. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs: make terminal figures render at a uniform text size The first pass stretched every terminal SVG to the same CSS width, so a narrow capture (compare) rendered its text larger than a wide one (the memory table) — visibly inconsistent, and out of step with the body text. rich exports SVGs with only a viewBox, so the browser was free to rescale each. Bake an explicit width/height at one shared SCALE into every asset (gen_doc_assets.py), and stop forcing a common width: each figure now keeps its natural size, centered, scrolling horizontally if it's wider than the column (like a code block). Result: identical monospace text size across all three, close to the page's code font. Also: slim the memory table to one time column so it's narrower, drop the now-unneeded long title on compare --diff (removes its right-side dead space), and wrap each image in <figure class="termshot"> (md_in_html). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <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
1 participant
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.
Stacked on top of #161. That PR restructured the docs around tasks but touched no CSS and added no assets — so the readability concerns (font too big, little color, no plots) were untouched. This pass fixes them.
What
1. Font too big on wide screens. Material for MkDocs scales the root font up to
137.5%(≥1600px) then150%(≥2000px), so body text and headings render oversized on desktop monitors. Pin it flat at125%across the wide breakpoints (one CSS override; tunable via a single value).2. No plots/colors → real, colored tool output. Before this, every page but the one executed notebook was prose + a monochrome
```consolefence, and the memray flamegraph the tool is built around was described but never shown. Added three colored terminal figures, captured as SVG from real runs:benchmem flamegraph --report summary— Home + profiling (localises the allocation: a<listcomp>owning 83% of peak)benchmem compare --diff— Home + compare-runs (the fix landing, greenΔ%)They live in
docs/assets/and are regenerated byscripts/gen_doc_assets.py(richexport_svgover real benchmark runs; local paths sanitised; auto-fit width; progress-spinner stripped).3. Notebook.
visualize.ipynbwas two plots + prose; added a coloredcompare --diffcell so the numbers behind the charts read in-page (ANSI renders as color in the built output).Note
gen_doc_assets.pyuses--report summary, nottree— memray'streereporter is an interactive TUI that never exits when its output is captured.Verification
mkdocs build --strictpasses (replicated the RTD build locally); all three SVGs copy into the site and are referenced with the.termshotclass; ANSI colors confirmed rendering in the notebook output HTML.🤖 Generated with Claude Code