docs(demos) Record every CLI command#560
Open
tony wants to merge 18 commits into
Open
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #560 +/- ##
=======================================
Coverage 83.30% 83.30%
=======================================
Files 32 32
Lines 4492 4492
Branches 903 903
=======================================
Hits 3742 3742
Misses 499 499
Partials 251 251 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
tony
force-pushed
the
screen-recording-2026-07-12
branch
from
d0032dc to
ca50fc2
Compare
tony
force-pushed
the
screen-recording-2026-07-12
branch
from
02cfe13 to
b88dc06
Compare
why: Every demo must record against a stable ~/code layout rather than a developer's real home, so the paths captured on screen are reproducible and free of personal directories. what: - Add setup-sandbox.sh, which builds the config and repositories each recording drives against, so any cast or tape can be re-rendered from a clean machine
why: Nine of the ten subcommands had no recorded session at all; the casts are the text-based source that the animated GIFs render from, so they belong under version control on their own. what: - Add asciinema .cast recordings for every subcommand, plus list --tree, each captured against the sandbox so recorded paths read as ~/code/...
why: The tapes are the declarative source that renders the GIF/MP4/WebM trio; sizing each to the rows its command actually occupies keeps demos from clipping output or trailing dead space. what: - Add a .tape per subcommand, each sized to its command's output and pointed at the sandbox, so the renders regenerate deterministically
why: GIF is the format embedded inline in the README and docs index — it needs no player and animates in any Markdown viewer, so it is the render every page links first. what: - Add the rendered GIFs: agg output for the asciinema casts and VHS output for the tapes
why: MP4 gives a compressed, seekable playback option for the longer demos, where an inline GIF would balloon in size for the same frames. what: - Add the VHS-rendered MP4 for each tape
why: WebM is the smallest of the three render formats and is preferred wherever the browser can play it, keeping the docs payload light. what: - Add the VHS-rendered WebM for each tape
why: The README's only visual was a single GIF, tucked above the donations footer, that predates most of the current CLI. Readers had to infer what add, discover, list, search, and status actually print. what: - Lead with a sync demo, so the core loop is visible before the install steps - Illustrate add, discover, list, search, and status beside their sections - Drop the stale demo GIF, which no longer resembled any command's output
why: Give readers a concrete view of each command beside its reference. what: - Embed the agg-rendered GIF for each top-level command - Show list tree mode in its existing reference section - Replace and remove the legacy homepage recording - Rebuild published docs when rendered GIFs change
why: The recorded demos live under docs/_static/demos/, and the shared Sphinx config sets html_static_path to _static, so the build copied all 67 demo files — tapes, casts, mp4/webm, and a second copy of each gif — into the published site. None of it is referenced there: pages embed the gifs from Sphinx's _images/ collection, and the README points at the committed repo files by raw URL. what: - Add "demos/**" to exclude_patterns so html_static_path skips the payload - Rendered gifs still reach the build via _images/; README URLs unaffected
why: Temporary — force the docs workflow to build and deploy THIS branch to the S3/CloudFront docs site so the migrated demos render on the live site for review. The published site should track master, so this MUST be reverted before merge. what: - Add screen-recording-2026-07-12 to the docs push trigger - Force PUBLISH on this ref so the deploy runs regardless of changed paths [DO NOT MERGE] — revert after previewing.
why: The demo GIFs render as width:100% with no intrinsic size, so the browser reserves no height until each GIF decodes and the page jumps as you move through the sidebar. Sphinx only emits dimensions for :scale:, and those come out as fixed pixels that distort the image on narrow viewports. what: - Add an html-page-context hook stamping each demo <img> with width:100%; aspect-ratio:W/H, computed from the source GIF - Reserves the correct box before load (no layout shift) while staying fluid and keeping lazy loading
why: The sync demo carries a large static dead-space band, and several obvious croppers (ffmpeg cropdetect black/mvedges, ImageMagick TrimBounds) silently fail on a non-black, full-frame terminal GIF. This records which approach actually works, with the outputs side by side. what: - Add an orphan comparison page rendering the original beside each approach's output, with dimensions and pass/fail notes - Only the ImageMagick union-trim recipe crops reliably; keep its result and a vertical-only variant as the viable options
why: The tight union-trim crop left only a 14px margin, so the content felt cramped against the edges. Restore a 28px margin on all sides — comfortable, and just past the terminal's native ~20px padding. what: - Re-render the D variant with -border 28 (382x181 -> 410x209) - Update the comparison page's dimensions and padding note
why: The previous pass framed the crop with #1e1e2e (Catppuccin), but the agg demos render in Dracula (#282A36), so the "padding" showed up as an ugly lighter-coloured border instead of breathing room. what: - Sample the real background (#282A36) and give an even 20px on all sides, verified bit-identical to the terminal bg so there is no visible seam - Gentler 4% trim fuzz so glyph edges are not clipped (395x193)
why: The crop comparison settled on approach D (union-trim + 10px of the terminal's own background); this shows every command's demo rendered that way, so the whole set can be judged as one before adopting it. what: - Crop all 11 command demos with the D pipeline (adapts per command) - Add an orphan gallery page embedding them with a crop-savings table
why: The demos carried wide static dead-space bands (mostly horizontal empty terminal). Applying the chosen D crop — ImageMagick union-trim plus 10px of the terminal's own sampled background — to the shipped gifs tightens every CLI page, the homepage, and the README with no page edits. what: - Replace the 11 asciinema demo gifs in place with their D crops; each adapts to its command's output (wide demos stay wide, short ones tighten) - Repoint the gallery page at the shipped files and drop the duplicate copies
why: The aspect-ratio hook forced width:100%, so a narrow demo (a 299px gif) was blown up to the ~750px column and went soft. The real pixels should show at their real size. what: - Inject width:<W>px; max-width:100% (was width:100%) so each demo renders at its true size, shrinks on a narrow screen, and never upscales — still aspect-ratio-reserved, so there is no layout shift
tony
force-pushed
the
screen-recording-2026-07-12
branch
from
b88dc06 to
5881194
Compare
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.
Summary
list --treeas VHS GIF/MP4/WebM tapes and asciinema casts with agg GIFs.Verification
uv run ruff format .— 95 files unchangeduv run py.test— 1,415 passed, 1 skipped; run twiceuv run ruff check . --fix --show-fixes— cleanuv run mypy— clean across 91 source filesjust build-docs— clean from-scratch build; all eleven GIFs copied