Documentation screenshots¶
The docs embed SVG screenshots and animated GIFs of the CLI in action. canair generates all of
them from the manifest at docs/screenshots/shots.yaml. You never craft or maintain them by hand.
freeze renders static command output (SVG).
vhs renders interactive text user interface (TUI) clips
and montage clips (GIF). Every asset is captured against the bundled, read-only
hyundai-ioniq-ae-ev profile with no device attached. It is therefore reproducible on any
machine and contains no owner-specific data.
brew install charmbracelet/tap/freeze vhs # one-time: the render tools
make screenshots # regenerate everything
make screenshots-only ONLY="bus decode-plot" # regenerate a subset
make screenshots-check # verify assets present + commands still run
--check is deliberately light. Continuous integration (CI) and the pre-push hook run it. It
needs neither freeze nor vhs, and it never byte-compares images, because images are not
reproducible. It verifies that every manifest asset exists, flags orphans, and runs each
screenshotted command device-free. A renamed command or a dropped flag therefore fails the check,
and the check tells you to regenerate.
When you change the output of a screenshotted command, re-render and commit the updated asset.
To add a shot, append an entry to shots.yaml (a rich command, a tui still or an anim tape)
and regenerate.
The monitor without a car¶
The monitor needs a bus, and the docs must not. scripts/gen/monitor_demo.py runs the production
monitor (controller, poll loop, decoders, renderer, Textual app) with a replay terminal in place
of the dongle. The terminal answers each request with the next payload that one capture session of
the bundled Ioniq profile recorded on the road, so the values move as they did. It runs on a
throwaway copy of the profile, so a recording or an edit made in it never reaches the repo, and its
link zone says replay.
- A
tuientry is a still: the script drives the app headless (--size,--keys,--wait) and the app exports the SVG itself, so nofreezeis needed. - The
monitor-tourtape runs the script invhs.vhscannot pressf10and typesalt+letteras two keys, so the tour reaches commands through the palette. The menus are in the stills. --checkrunsmonitor_demo.py --check: three headless poll cycles over the replay.
uv run python scripts/gen/monitor_demo.py # the demo, in your terminal
python3 scripts/gen/gen_screenshots.py --only monitor monitor-menu monitor-tour
Do not screenshot views that show free-text capture notes or labels (for example
captures --sessions). Those views can leak personally identifiable information (PII) into public
docs.
A few anim assets are marked live: true. They are recordings of the monitor TUI that
polls a real car. They are not reproducible, so the default make screenshots skips them and
--check only verifies that the file is present. The two that exist (monitor-bms,
monitor-drivetrain) predate the monitor's menu bar and zoned status line, so the docs show the
replayed recordings instead until they are re-recorded. Re-record one by hand when a vehicle is
reachable: