Skip to content

DEMO_GIF.md

Latest commit

 

History

History
69 lines (49 loc) · 1.88 KB

DEMO_GIF.md

File metadata and controls

69 lines (49 loc) · 1.88 KB
Raw

Demo GIF Workflow

Use this workflow to generate a repeatable GIF for the README, GitHub release, and PyPI project page. The goal is to show the real pythonlings first-run flow, not a mocked terminal.

Recommended Tool

Use VHS. It records scripted terminal sessions and produces a GIF without manual screen capture.

brew install charmbracelet/tap/vhs

Generate the GIF

From the repository root:

pip install -e ".[dev]"
scripts/generate_demo_gif.sh

To use a specific VHS binary, set VHS_BIN:

VHS_BIN=/path/to/vhs scripts/generate_demo_gif.sh

If Homebrew VHS fails on macOS with could not open ttyd and ERR_CONNECTION_REFUSED, use a newer VHS build or run VHS through Docker. That failure happens before Pythonlings starts.

The tape writes:

docs/assets/demos/pythonlings-demo.gif

Review the GIF before committing it. Keep the recording under 20 seconds so it loads quickly on GitHub and PyPI.

What the Demo Shows

The scripted flow should stay focused on the first-time user path:

  1. Run pythonlings with no setup — it creates ~/.pythonlings and opens the first pending exercise (zero-config first run).
  2. Show the first pending exercise in the coding screen.
  3. Open and close the local docs window with F5 and Esc.
  4. Open the topic picker with F4.
  5. Quit with Ctrl+Q.
  6. Show topic progress with pythonlings list.
  7. Show a hint and official docs link with pythonlings hint variables1.

Fallback Workflow

If VHS cannot control the TUI reliably on a machine, record an asciinema cast and render it with agg:

brew install asciinema agg
asciinema rec docs/assets/demos/pythonlings.cast
agg docs/assets/demos/pythonlings.cast docs/assets/demos/pythonlings-demo.gif

The VHS path is preferred because docs/demo.tape keeps the public demo repeatable across releases.