docs: add VHS-based interactive screenshot generation

[HankyStyle]

Description

This PR adds support for generating interactive GIF screenshots for cz init and cz commit commands using VHS (Video Home System), a tool for generating terminal GIFs from code.

Why VHS?

VHS is a modern tool for generating terminal recordings as GIFs.
Benefits:

• Reproducible: Tape files ensure consistent output
• Version-controlled: Configuration is code
• Cross-platform: Works on macOS, Linux, and Windows

Checklist

• I have read the contributing guidelines

Was generative AI tooling used to co-author this PR?

• Yes (antigravity + Claude Sonnect 4.5)

Code Changes

• Add test cases to all the changes you introduce
• Run uv run poe all locally to ensure this change passes linter check and tests
• Manually test the changes:
  • Verify the feature/bug fix works as expected in real-world scenarios
    • Tested python scripts/gen_cli_help_screenshots.py locally
    • Verified both init.gif and commit.gif are generated correctly
  • Test edge cases and error conditions
    • Tested with missing VHS installation (proper error message)
    • Tested with missing tape files (proper warning message)
  • Ensure backward compatibility is maintained
    • Existing gen_cli_help_screenshots() function unchanged
  • Document any manual testing steps performed
    • See "Steps to Test This Pull Request" section below
• Update the documentation for the changes

Expected Behavior

1. Local Generation: Running python scripts/gen_cli_help_screenshots.py should generate:

   • 11 SVG files in docs/images/cli_help/ (CLI help screenshots)
   • docs/images/init.gif (interactive demo of cz init)
   • docs/images/commit.gif (interactive demo of cz commit)

2. CI/CD: When documentation workflow runs:

   • VHS is installed automatically
   • GIF screenshots are generated alongside SVG screenshots
   • Both file types are committed to the repository

Steps to Test This Pull Request

Prerequisites

# Install VHS
brew install vhs  # macOS
# or follow: https://github.com/charmbracelet/vhs#installation

Local Testing

# 1. Checkout this branch
git checkout feat/interactive-screenshots

# 2. Run the screenshot generation script
python scripts/gen_cli_help_screenshots.py

# 3. Verify generated files
ls -lh docs/images/*.gif
open docs/images/init.gif
open docs/images/commit.gif

Additional Context

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.98%. Comparing base (dd972c9) to head (32058e3).
⚠️ Report is 2 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1862   +/-   ##
=======================================
  Coverage   97.98%   97.98%           
=======================================
  Files          60       60           
  Lines        2686     2686           
=======================================
  Hits         2632     2632           
  Misses         54       54           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[HankyStyle]

lol. I found that I can't edit this PR title name after I created it.
Please help me change it to feat(docs): add VHS-based interactive screenshot generation or other better naming.

[Lee-W]

not really a feat (at least not to commitizen itself), so I changed it to docs

[bearomorphism]

lol. I found that I can't edit this PR title name after I created it. Please help me change it to feat(docs): add VHS-based interactive screenshot generation or other better naming.

I heard from my friend that some github preview features have so terrible UI that people cannot find where to edit the PR title.

[bearomorphism]

Thank you for your contribution of this great documentation improvement! The new gifs look beautiful!

Nothing is really blocking this PR but the comments related to demo.gif.

[bearomorphism]

As a follow up, this can also be used to regenerate bump.gif, which can be in a separate PR

[HankyStyle]

Thanks @bearomorphism

I created a separate script called gen_cli_interactive_gifs.py under the scripts/ directory, which outputs gifs into a separate directory (images/cli_interactive/ ).

Here is my reorganized directory structure.

docs/images
├── bump.gif
├── bump.yml
├── cli_help
│   └── cz_version___help.svg
├── cli_interactive
│   ├── commit.gif
│   └── init.gif
├── commit.tape
└── init.tape

And I also modified pyproject.toml to support parallel screenshot generation:

"doc:screenshots".parallel = [
    { script = "scripts.gen_cli_help_screenshots:gen_cli_help_screenshots" },
    { script = "scripts.gen_cli_interactive_gifs:gen_cli_interactive_gifs" },
]

Let me know if you have any suggestions or preferences for the placement of tape/gif files.

[bearomorphism]

Thanks!