---------------------------------------------------------------------- This is the API documentation for the gdtest_termshow library. ---------------------------------------------------------------------- ## Functions Public functions greet(name: str) -> str Greet a user by name. Parameters ---------- name The name to greet. Returns ------- str A greeting string. init_project(path: str, *, template: str = 'default') -> dict Initialize a new project at the given path. Parameters ---------- path Directory to create the project in. template Project template to use. Returns ------- dict Project metadata. run_task(task_name: str, *, verbose: bool = False) -> int Run a named task. Parameters ---------- task_name Name of the task to execute. verbose Enable verbose output. Returns ------- int Exit code (0 for success). ---------------------------------------------------------------------- This is the User Guide documentation for the package. ---------------------------------------------------------------------- ## Installation & First Run Watch this quick demo to see `my-tool` in action — from installation through your first build: {{< termshow file="demos/getting-started" pause_on_chapters="true" >}} ### What just happened? The recording above shows three steps: 1. **Install** — `pip install my-tool` fetches the package from PyPI 2. **Initialize** — `my-tool init` scaffolds a new project 3. **Build** — `my-tool run --verbose` executes the build pipeline You can click any chapter marker in the timeline to jump directly to that step, or use keyboard shortcuts: | Key | Action | |-----|--------| | Space | Play/Pause | | ← / → | Seek 5 seconds | | . | Next chapter | | , | Previous chapter | ## Next Steps Now that you have `my-tool` installed, check out the [TUI Interface](02-tui-interface.qmd) guide for the interactive mode. ## Interactive Mode `my-tool` includes a full-screen terminal interface for visual project management. Launch it with: ```bash my-tool --interactive ``` Here's how it looks: {{< termshow file="demos/tui-demo" pause_on_chapters="true" >}} ### Navigation The TUI uses standard terminal navigation: - **↑/↓** arrows to move between items - **Enter** to select/confirm - **q** to quit - **Esc** to go back one level ### Features The interactive mode provides: - Project creation wizard - File browser with preview - Live build output - Configuration editor ## Creating Your Own Recordings Great Docs makes it easy to record, edit, and embed terminal sessions in your documentation. ### Recording ```bash # Start recording great-docs termshow record demos/my-demo.termshow # Perform your CLI actions... # Press Ctrl+D or type 'exit' to stop ``` ### Editing with Scripts Create a `.termshow.yml` file alongside your recording to add chapters, annotations, and timing adjustments: ```yaml source: demos/my-demo.termshow settings: idle_time_limit: 2.0 window_chrome: colorful chapters: - at: 0.0 label: Introduction - at: 10.0 label: Main Feature annotations: - at: 2.0 duration: 3.0 text: This step installs dependencies position: top-right style: callout cuts: - from: 5.0 to: 8.0 type: ellipsis ``` ### Rendering ```bash # Render SVG frames great-docs termshow render demos/my-demo.termshow ``` ### Embedding Use the `termshow` shortcode in your `.qmd` files: ```markdown {{< termshow file="demos/my-demo" pause_on_chapters="true" >}} ``` ### Importing Existing Recordings Already have recordings from asciinema or VHS? ```bash # Import from asciinema great-docs termshow import-cast recording.cast demos/my-demo # Import from VHS tape great-docs termshow import-tape demo.tape demos/my-demo ``` ## Overview The **termshow** is Great Docs' built-in terminal recording player. It renders pre-recorded terminal sessions as interactive, frame-accurate SVG animations directly in your documentation pages — no JavaScript framework dependencies, no external services. Key capabilities: - Frame-accurate SVG rendering of terminal output - Chapter-based navigation with labeled markers - Contextual annotations that appear at specific timestamps - Keyboard shortcuts for power users - Adjustable playback speed (0.5× to 3×) - Works offline and with `file://` protocol (all data embedded inline) - Responsive layout that scales to any viewport width - Light/dark theme support (follows the site theme) ### Live Demo Here's a recording of real Great Docs CLI commands — `scan`, `lint`, and `term render` — running against this very package: {{< termshow file="demos/great-docs-cli" pause_on_chapters="true" >}} ## The Recording Format Termshow uses a two-file system for each recording: ### The `.termshow` File This is the raw terminal recording in NDJSON format. Each line is a JSON array with `[delay, event_type, data]`: ```json {"version": 1, "format": "termshow", "term": {"cols": 80, "rows": 20}} [0.5, "o", "$ "] [0.1, "o", "echo hello"] [0.6, "o", "\r\nhello\r\n"] [1.0, "m", "Command executed"] ``` Event types: | Type | Meaning | |------|---------| | `"o"` | Output — terminal data written to stdout | | `"i"` | Input — user keystrokes (for display purposes) | | `"m"` | Marker — internal marker used for chapter sync | The header line sets terminal dimensions and metadata. ### The `.termshow.yml` Script File This companion file defines chapters, annotations, timing adjustments, and visual settings: ```yaml source: demos/my-recording.termshow settings: idle_time_limit: 2.0 # Cap any idle gap to 2 seconds window_chrome: colorful # Window decoration style theme: monokai # Terminal color scheme font_size: 14 # Font size in pixels chapters: - at: 0.0 label: Introduction - at: 5.0 label: Configuration - at: 12.0 label: Running Tests annotations: - at: 1.0 duration: 3.0 text: This installs all required dependencies position: top-right style: callout - at: 6.0 duration: 2.5 text: Configuration is auto-detected position: bottom-right style: subtle cuts: - from: 8.0 to: 11.0 type: ellipsis # Shows '…' for the cut section ``` ## Settings Reference | Setting | Default | Description | |---------|---------|-------------| | `idle_time_limit` | `3.0` | Maximum seconds for any idle gap | | `window_chrome` | `colorful` | Window decoration: `colorful`, `plain`, `none` | | `theme` | (auto) | Terminal color scheme | | `font_size` | `14` | Font size in rendered SVG (px) | | `line_height` | `1.2` | Line height multiplier | | `padding` | `12` | Inner padding of the terminal area (px) | ## Annotation Styles Annotations appear as overlays on the terminal at specified times. Three styles are available: | Style | Appearance | |-------|------------| | `callout` | Semi-opaque dark card with accent border | | `subtle` | Lighter, smaller text — less intrusive | | `highlight` | Amber-tinted with warm border — draws attention | Positions: `top-left`, `top-right`, `bottom-left`, `bottom-right`. ## Embedding in Pages Use the `termshow` Quarto shortcode in any `.qmd` file: ````markdown ## Basic usage {{< termshow file="demos/getting-started" >}} ## With chapter pausing {{< termshow file="demos/workflow" pause_on_chapters="true" >}} ## Autoplay with custom speed {{< termshow file="demos/quick" autoplay="true" speed="1.5" >}} ```` ### Shortcode Options | Option | Default | Description | |--------|---------|-------------| | `file` | (required) | Path to `.termshow` file (without extension) | | `autoplay` | `false` | Start playing automatically on page load | | `loop` | `false` | Loop playback when reaching the end | | `speed` | `1` | Initial playback speed multiplier | | `pause_on_chapters` | `false` | Auto-pause at each chapter boundary | | `controls` | `true` | Show the control bar | | `theme` | `auto` | Player theme: `auto`, `dark`, or `light` | ## Player Controls The player provides a full set of interactive controls: ### Control Bar From left to right: 1. **Play/Pause button** — Toggles playback. Shows ↺ (replay) at the end. 2. **Current time** — Elapsed time counter. 3. **Timeline scrub bar** — Click anywhere to seek. Chapter markers appear as gold ticks with wider hit targets for easy clicking. 4. **Remaining time** — Counts down to zero during playback. 5. **Speed button** — Cycles through 0.5×, 1×, 1.5×, 2×, 3×. ### Chapter Bar A thin overlay at the top of the player shows the name of the current chapter, updating as playback progresses. ### Center Overlay A semi-transparent button in the center of the viewport: - **Before playback** — Shows ▶ as a call-to-action. - **After playback ends** — Shows ↺ to indicate replay. Clicking returns the player to its initial state (frame 0, ready to play). - **During chapter pauses** — Hidden, so the terminal content remains fully visible. ### Keyboard Shortcuts Click the player viewport first to give it focus, then use: | Key | Action | |-----|--------| | `Space` | Play / Pause (or reset from ended state) | | `→` | Seek forward 5 seconds | | `←` | Seek backward 5 seconds | | `.` | Jump to next chapter | | `,` | Jump to previous chapter | ## Workflow The full termshow workflow from recording to rendered page: ```text 1. Record great-docs termshow record demos/my-demo.termshow 2. Edit script Create/edit demos/my-demo.termshow.yml 3. Preview great-docs termshow play demos/my-demo.termshow 4. Embed Add {{< termshow ... >}} to your .qmd 5. Build great-docs build (renders SVG frames automatically) ``` ### Step 1: Record ```bash great-docs termshow record demos/install-guide.termshow ``` This launches a recording session. Everything you type and see in the terminal is captured with precise timing. Press `Ctrl+D` or type `exit` to end the recording. ### Step 2: Create the Script Create `demos/install-guide.termshow.yml` alongside the recording. Define chapters at logical breakpoints in your workflow, and add annotations to explain what's happening: ```yaml source: demos/install-guide.termshow settings: idle_time_limit: 1.5 window_chrome: colorful chapters: - at: 0.0 label: Setup - at: 8.0 label: Install - at: 15.0 label: Verify annotations: - at: 1.0 duration: 3.0 text: Start by activating the virtual environment position: top-right style: callout ``` ### Step 3: Preview ```bash great-docs termshow play demos/install-guide.termshow ``` This plays the recording in your terminal so you can verify timing and check that chapter boundaries feel natural. ### Step 4: Embed Add the shortcode to any user guide or documentation page: ```markdown {{< termshow file="demos/install-guide" pause_on_chapters="true" >}} ``` ### Step 5: Build ```bash great-docs build ``` During the build, Great Docs: 1. Finds all `.termshow` files in your project 2. Renders each recording into a series of SVG keyframes 3. Generates a `manifest.json` with timing, chapters, and annotations 4. The Lua shortcode filter embeds the manifest and all SVG frames inline in the HTML — no runtime fetches needed ## Importing Existing Recordings Already have terminal recordings from other tools? Import them: ```bash # From asciinema (.cast files) great-docs termshow import-cast recording.cast demos/my-demo # From VHS (.tape files) great-docs termshow import-tape demo.tape demos/my-demo ``` The import preserves timing and terminal dimensions. You'll still want to create a `.termshow.yml` script to add chapters and annotations. ## Tips & Best Practices - **Keep recordings short** — 15–30 seconds is ideal. Split longer workflows into multiple recordings. - **Use `idle_time_limit`** — Caps long pauses so viewers aren't waiting through your thinking time. - **Place chapters at logical transitions** — Each chapter should represent one distinct step in the workflow. - **Use `pause_on_chapters`** for tutorials — Gives readers time to absorb each step before the next one plays. - **Annotations are brief** — One sentence max. They complement the terminal output, not replace it. - **Test at different speeds** — Make sure annotations are still readable at 1.5× and 2× speed. - **80 columns, 20 rows** works well for most CLI recordings. Use 60 columns for narrower TUI demos. ## Architecture Under the hood, termshow works in two phases: **Build time** (Python + Lua): 1. `core.py` discovers `.termshow` files and calls the renderer 2. The renderer parses the NDJSON recording + YAML script 3. It produces SVG keyframes at each visual change point 4. A `manifest.json` captures timing, chapters, and annotation data 5. The Lua shortcode embeds everything inline as `