docs: Add screen recordings for every CLI subcommand#1077
Open
tony wants to merge 6 commits into
Open
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #1077 +/- ##
=======================================
Coverage 82.56% 82.56%
=======================================
Files 31 31
Lines 2770 2770
Branches 518 518
=======================================
Hits 2287 2287
Misses 346 346
Partials 137 137 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
7f250aa to
c82c908
Compare
c82c908 to
0b0c32a
Compare
0b0c32a to
03b77d3
Compare
03b77d3 to
632115e
Compare
why: Demo GIFs must render at their real size without shifting the page as they load, and the recorded sources (tapes, casts, mp4/webm) should stay in the repo without being published to the static site. what: - Add the aspect_ratio extension, stamping each demo <img> with width:<W>px; max-width:100%; aspect-ratio:W/H from the source GIF, so narrow demos never upscale and the browser reserves the box up front - Index the embedded asciinema GIFs last so their cropped size wins the basename over same-named vhs/legacy gifs regardless of walk order - Exclude "demos/**" from the build; referenced GIFs still reach the site via Sphinx's _images/ collection
why: Give each tmuxp subcommand a short terminal demo so the docs, README, and homepage show real output instead of only prose. what: - Add asciinema casts and agg-rendered GIFs (cropped to content with a 10px sampled-background margin) for ls, load, search, freeze, convert, shell, edit, import, and debug-info - Add VHS tapes with rendered GIF/MP4/WebM source assets - Record the load demo attached (no -d) over a small Flask web-dev workspace, so it shows tmuxp building windows and panes and handing a live session over before detaching - Add setup-sandbox.sh, which builds an isolated, PII-free demo sandbox (sandbox venv install + fun workspace configs + TMUX_TMPDIR server) themed with a Solarized Dark .tmux.conf
why: Show each command's real output next to its reference. what: - Embed the demo GIF on each of the nine CLI subcommand pages - Replace the legacy shell -c screencast with the recorded shell demo - Resize the load embed and correct its alt text to match the attached recording
why: Let readers on GitHub and PyPI see tmuxp's commands in action. what: - Embed the load, ls, shell, freeze, convert, and debug-info demos under their sections, replacing the stale hand-recorded screenshot - Size each <img> to the demo's real pixel width so narrow demos are not upscaled and blurred, and match the load embed to the attached recording
why: Lead the homepage with the pitch and the navigation cards; show the load demo once, at the foot, instead of between the intro and the cards. what: - Replace the stale hand-recorded homepage screencast with the attached load demo - Place it in a Screenshot section at the bottom of the page, sized and alt-texted to match the attached recording
why: Temporarily build and deploy the docs from this branch so the new CLI demo recordings can be previewed on the live site before merge. what: - Add screen-recording-2026-07-12 to the docs workflow push trigger Drop this commit before merging; it exists only to trigger a preview deploy and must not reach master.
632115e to
fa5fc9a
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
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
Adds a short terminal demo for every
tmuxpsubcommand and wires them intothe CLI reference, the homepage, and the README. Each demo shows the command's
real output — recorded against an isolated, PII-free sandbox — so readers see
what
tmuxp ls,load,search,freeze,convert,shell,edit,import, anddebug-infoactually do.What's included
Four atomic commits:
docs(demos)— asciinema casts + agg-rendered GIFs (cropped to contentwith a 10px sampled-background margin), VHS tapes with GIF/MP4/WebM renders,
and
setup-sandbox.sh, which builds the isolated demo sandbox.docs(sphinx)— theaspect_ratioextension (stamps each demo<img>with
width:<W>px; max-width:100%; aspect-ratio:W/Hso demos render at realsize with no layout shift and narrow demos never upscale) and a
demos/**build exclude (keeps the tape/cast/mp4/webm sources in the repo but out of
the published site; referenced GIFs still reach the build via
_images/).docs(cli)— the demo GIF on each of the nine subcommand pages, plus aloadhero on the homepage (replacing the stale hand-recorded screencast).docs(README)— theload,ls,shell,freeze,convert, anddebug-infodemos under their sections.Notes for reviewers
with
HOME/XDG_CONFIG_HOME/TMUX_TMPDIRredirected, so every path onscreen renders as
~/…or/tmp/tmuxp-demo/…andtmuxruns on a throwawayserver.
debug-infois recorded with no server so its output stays compactand its own import path tilde-collapses. Re-render anything with
bash docs/_static/demos/setup-sandbox.shthen the tape/cast.width:100%. The Sphinx hook indexes the embeddeddemos/asciinemaGIFs last so a command's cropped size wins its basenameover the same-named
vhs/source render; README<img>tags use real pixelwidths so nothing is upscaled.
raw.githubusercontent.com/…/master/…links (required for PyPI's long-description rendering); they resolve once
this merges to
master.Verification
uv run ruff format·uv run ruff check·uv run mypy·just build-docs(clean, no new warnings) all pass.
uv run pytestis green apart from apre-existing flaky spinner test (
test_spinner_enabled_output) unrelated tothese docs-only changes.