Skip to content

docs: Add screen recordings for every CLI subcommand#1077

Open
tony wants to merge 6 commits into
masterfrom
screen-recording-2026-07-12
Open

docs: Add screen recordings for every CLI subcommand#1077
tony wants to merge 6 commits into
masterfrom
screen-recording-2026-07-12

Conversation

@tony

@tony tony commented Jul 13, 2026

Copy link
Copy Markdown
Member

Summary

Adds a short terminal demo for every tmuxp subcommand and wires them into
the 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, and debug-info actually do.

What's included

Four atomic commits:

  • docs(demos) — asciinema casts + agg-rendered GIFs (cropped to content
    with a 10px sampled-background margin), VHS tapes with GIF/MP4/WebM renders,
    and setup-sandbox.sh, which builds the isolated demo sandbox.
  • docs(sphinx) — the aspect_ratio extension (stamps each demo <img>
    with width:<W>px; max-width:100%; aspect-ratio:W/H so demos render at real
    size 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 a
    load hero on the homepage (replacing the stale hand-recorded screencast).
  • docs(README) — the load, ls, shell, freeze, convert, and
    debug-info demos under their sections.

Notes for reviewers

  • Isolation. Demos record against a sandbox venv install of this checkout
    with HOME/XDG_CONFIG_HOME/TMUX_TMPDIR redirected, so every path on
    screen renders as ~/… or /tmp/tmuxp-demo/… and tmux runs on a throwaway
    server. debug-info is recorded with no server so its output stays compact
    and its own import path tilde-collapses. Re-render anything with
    bash docs/_static/demos/setup-sandbox.sh then the tape/cast.
  • Real sizing over width:100%. The Sphinx hook indexes the embedded
    demos/asciinema GIFs last so a command's cropped size wins its basename
    over the same-named vhs/ source render; README <img> tags use real pixel
    widths so nothing is upscaled.
  • README image URLs are absolute 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 pytest is green apart from a
pre-existing flaky spinner test (test_spinner_enabled_output) unrelated to
these docs-only changes.

@codecov

codecov Bot commented Jul 13, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.56%. Comparing base (0c9f8c2) to head (fa5fc9a).

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.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@tony tony force-pushed the screen-recording-2026-07-12 branch from 7f250aa to c82c908 Compare July 13, 2026 02:14
@tony tony force-pushed the screen-recording-2026-07-12 branch from c82c908 to 0b0c32a Compare July 13, 2026 11:36
@tony tony force-pushed the screen-recording-2026-07-12 branch from 0b0c32a to 03b77d3 Compare July 15, 2026 00:39
@tony tony force-pushed the screen-recording-2026-07-12 branch from 03b77d3 to 632115e Compare July 15, 2026 00:52
tony added 6 commits July 14, 2026 19:58
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.
@tony tony force-pushed the screen-recording-2026-07-12 branch from 632115e to fa5fc9a Compare July 15, 2026 00:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant