Open
Conversation
Add docs/topics/ directory structure to provide comprehensive markdown documentation beyond basic CLI usage. This enables users to access detailed guides and examples for complex workflows through organized topic directories. Refactor help command implementation by moving logic from bin/genesis inline code to Genesis::Commands::Core::help() method for better maintainability and extensibility. Changes include: - New docs/topics/ with categorized subdirectories: * 00-getting-started/ - Initial setup guides * 10-environments/ - Environment file management * 30-secrets-management/ - Secrets handling * 50-kits/ - Kit access, usage and development * 60-bosh/ - BOSH integration topics * 70-troubleshooting/ - Debug and problem solving * 90-reference-guides/ - Technical references - Help command now supports new options: * --list-topics/-l: List available help topics * --topic/-t <name>: Show specific topic help * --command/-c <name>: Show specific command help - Removed GENESIS_COMMAND environment variable assignment from bin/genesis main loop, now handled in prepare_command() Users can access extended documentation through: genesis help --list-topics genesis help --topic <topic-name> Topic markdown files should be placed in appropriate docs/topics/ subdirectories for automatic discovery, and should be named using <concise-meaningful-topic-name>.md. Genesis will detect and format them into title-case for presentation.
This commit introduces an extensive help topics system that provides in-depth documentation directly accessible through the Genesis CLI, going beyond basic command usage to cover concepts, best practices, and detailed guides. - **Help Topics Command**: `genesis help topics` lists all available documentation topics - **Topic Viewing**: `genesis help <topic>` displays topic index with subtopics - **Subtopic Navigation**: `genesis help <topic>/<subtopic>` shows specific guides - **Markdown Rendering**: Full markdown support with proper formatting in terminal Created 53 documentation files organized into 7 main categories: 1. **Getting Started** (00-getting-started/) - Introduction to Genesis concepts - Installation guide - Basic configuration - First deployment walkthrough - Core concepts explained - Next steps guidance 2. **Environment Management** (10-environments/) - Naming conventions and hierarchical structure - Configuration file organization - BOSH integration details - Vault path management - Match mode operations - Best practices for production 3. **Secrets Management** (30-secrets-management/) - Vault and CredHub integration - Secret types and generation - Rotation procedures - Manual secret management - Security best practices 4. **Genesis Kits** (50-kits/) - Using existing kits - Authoring new kits - Hook development guide - Kit structure and features - Testing strategies - Available community kits 5. **BOSH Integration** (60-bosh/) - BOSH overview and concepts - Director management - Cloud and runtime configs - Stemcells and releases - Troubleshooting BOSH issues 6. **Troubleshooting** (70-troubleshooting/) - Common issues and solutions - Trace logging guide - Debugging deployments - Error message reference - Kit development problems 7. **Reference Guides** (90-reference-guides/) - Environment variables - Genesis configuration files - Hook reference - Manifest operators - Runtime configurations - **New Module**: `lib/Genesis/HelpTopics.pm` handles topic discovery and rendering - **Command Integration**: Modified `help()` in Commands/Core.pm to support topics - **General Help Update**: Added help topics mention in main help output - **Library Structure**: Topics stored in `lib/Genesis/Help/Topics/` for packaging - Proper error handling for missing topics - Breadcrumb navigation for context - Terminal width-aware rendering - Maintains backward compatibility with existing help system - Efficient topic discovery with numbered directory ordering This enhancement significantly improves the Genesis user experience by providing, easily accessible documentation without requiring external resources or internet access.
wayneeseguin
force-pushed
the
v3.1.x-feature/help-topics
branch
from
67da50a to
f6872f7
Compare
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
2 participants
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.
Add initial help topics documentation.