Add comprehensive progressive documentation with examples and animation support#15
Draft
Add comprehensive progressive documentation with examples and animation support#15
Conversation
- Create docs/ folder with sequenced documentation - 1_commands.md: Basic command structure - 2_arguments.md: Command arguments - 3_flags.md: Flags and global flags - 4_config.md: Configuration system (flags, env vars, files) - 5_help.md: Help system - 6_text_prompts.md: Basic text prompting with TextPrompter - 7_validation.md: Input validation - 8_terminal_prompts.md: Advanced terminal prompts (select, multi-select) - 9_surveys.md: Survey extension for chaining prompts - 10_extensions.md: Extension system architecture - docs/README.md: Navigation and overview Documentation follows progressive dependencies: - Simple commands → Arguments → Flags → Config → Help - Text Prompts → Validation → Terminal Prompts → Surveys → Extensions Each section includes working code examples that build on previous concepts.
- Create docs/assets/ directory for WebP animations
- Add assets/README.md with recording guidelines
- Update documentation files to reference animations
- Add placeholder image references following {document}_{n}.webp pattern
Animations will be recorded separately and added to the repo.
The documentation now includes both code examples and animation references.
- Update README with maximum quality settings (quality 100) - Add -loop 0 flag for infinite looping animations - Create record.sh script for easy recording workflow - Create convert_to_webp.sh for converting existing GIFs - Add Makefile for convenient commands - Emphasize crisp text readability with quality 100 The scripts automate: 1. Recording with asciinema 2. Converting to GIF with agg 3. Converting to WebP with maximum quality and looping 4. Cleaning up intermediate files
- List all animations needed for documentation - Provide specific commands for each animation - Include batch recording script template - Add tips for quality recording
- Create docs/code/ directory structure - Add runnable examples for each documentation section: - commands: basic, subcommands, help - arguments: basic, multiple - flags: basic usage - config: precedence demonstration - text_prompts: basic, defaults, confirm - validation: argument and prompt validation - terminal_prompts: select, multi-select, tab completion - Each example is standalone and can be compiled independently - Add go.mod for examples module with clix replace directive - Add README with usage instructions These examples can be used to record the documentation animations.
- Move each example into its own directory with main.go - Structure: commands/example1_basic/main.go - This allows multiple main functions without conflicts - Update README with new directory structure and usage - All examples can now be run independently
- Each example now has its own go.mod with replace directive - Add Makefile to auto-generate go.mod files - Examples can be run independently from their directories
- Fix directory navigation in Makefile - Use relative path ../../.. for replace directive - All examples now have working go.mod files
- Ensure all example go.mod files have replace directive for clix - All 15 examples now have working go.mod files - Examples can be run independently
- Update path from ../../.. to ../../../../.. (correct depth) - Examples can now properly reference clix module
- Change from ../../../../.. to ../.. - Path is relative to docs/code/, pointing to root clix module - All examples now work correctly
- Calculate correct relative path based on directory depth - Each example now has correct replace directive - Examples can be run from their directories
- Correctly calculate depth and add 1 for root level - All examples now have correct replace paths - Examples compile and run successfully
- Update all examples to use app.Run(context.Background(), nil) - Add context import where needed - Regenerate go.mod files with correct paths - Examples now compile and run successfully
- All examples are 4 levels deep: example -> category -> code -> docs -> root - Use fixed path ../../../../ instead of dynamic calculation - All examples now compile and run successfully
- Replace AddSubcommand() calls with direct Subcommands assignment - Matches actual clix.Command API
- Step-by-step instructions for recording animations - Installation instructions for tools - Specific commands for each animation - Tips for good recordings - Troubleshooting section
- Explicitly label struct-based API as 'Primary' - Label functional options as 'Convenience' - Add side-by-side examples showing both APIs - Explain that both can be mixed (PromptRequest implements PromptOption) - Clarify that struct-based API is recommended for consistency - Update validation docs to show both API styles
- Add missing context imports to arguments and validation examples - Replace deprecated Description field with Short in example3_help - Fix StringVar/IntVar API usage (Value should be in options struct, not separate param) - Add missing context imports to flags and config examples - Run go mod tidy for terminal_prompts examples to fix go.sum issues All 15 examples now compile successfully.
- Set PS1 and PROMPT to minimal '$ ' before recording - Update documentation to explain the minimal prompt feature - Add record_minimal.sh alternative script for custom prompts - Helps create cleaner, more professional recordings
The previous approach of exporting PS1/PROMPT didn't work because asciinema starts a new shell that loads .zshrc/.bashrc, overriding the prompt. Now using asciinema's -c flag to run a custom shell command that: - For zsh: Uses -f to skip .zshrc, sets PROMPT='$ ', then exec zsh - For bash: Uses --norc to skip .bashrc, sets PS1='$ ', then exec bash This ensures the minimal prompt is used regardless of shell configuration.
- Script now detects if user manually set PROMPT/PS1 and uses that - Better export handling to ensure prompt persists through exec - If user runs 'PROMPT="$ " ./record.sh', it will use that prompt
- Simplify record.sh - just document manual PROMPT setting - Add new 1.5_styling.md section after commands to show lipgloss early - Add styling example code (styling/example1_basic) - Update table of contents to include styling section - Update 1_commands.md to reference styling as next step
- Moved all docs/*.md files to docs/tutorial/{name}/README.md
- Copied relevant main.go files to same directories
- Updated all internal links to use new structure
- Removed docs/code/ directory (code now lives with docs)
- Updated main README.md with new structure
- Each tutorial now has: README.md, main.go, go.mod all in one place
- Each tutorial now has its webp files alongside README.md and main.go - Updated all asset links in README files to use relative paths - All tutorial assets (docs, code, webps) now in one place per tutorial
- Recovered main.go and go.mod files from git history - Moved remaining .md files to tutorial directories as README.md - All tutorial directories now have README.md, main.go, and go.mod
- Added code examples extracted from README files - All tutorial directories now have README.md, main.go, and go.mod - Tutorials 5_help, 9_surveys, and 10_extensions don't need code examples
- 5_help: Demonstrates help extension (adds 'help' command) - 9_surveys: Demonstrates survey extension with dynamic questions - 10_extensions: Demonstrates creating a custom extension All tutorial directories now have README.md, main.go, and go.mod
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
1 participant
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.
Overview
This PR adds comprehensive, progressive documentation for the CLIX library, organized sequentially to build understanding from basic commands through advanced features like surveys.
What's Included
Documentation Structure
Standalone Code Examples
docs/code/organized by topicmain.goandgo.modAnimation Support
RECORDING_GUIDE.md) with step-by-step instructionsrecord.sh,convert_to_webp.sh) for automated recordingDocumentation Sections
Key Features
Next Steps
After merge, animations should be recorded and added to the
docs/assets/directory as referenced in the markdown files.