topics

                   Cobra Topics Extension
                   ======================

The cobrax/topics package provides a pluggable, topic-based help system for
Cobra CLI applications. It extends the default Cobra help functionality to
support arbitrary help topics loaded from files.

Features
--------

• File-based help topics with configurable extensions
• Default support for .txt and .md files
• Customizable extensions (e.g., add .txxt, .rst)
• Automatic topic discovery from directory
• Flag-style topic support (--dry-run → dry-run)
• Seamless fallback to Cobra's original help
• Shell completion for topics
• Easy single-function integration

Usage
-----

1. Import the package:

   import "github.com/arthur-debert/dodot/pkg/cobrax/topics"

2. Create help topic files in your project:

   cmd/myapp/topics/
   ├── option-dry-run.txt    # For flag/option documentation
   ├── option-verbose.txt    # Prefix with "option-" for flags
   ├── architecture.md       # General topics without prefix
   └── getting-started.txxt

3. Initialize in your CLI:

   rootCmd := &cobra.Command{...}
   
   // Option 1: Use default extensions (.txt, .md)
   if err := topics.Initialize(rootCmd, "cmd/myapp/topics"); err != nil {
       log.Debug().Err(err).Msg("Failed to initialize topics")
   }
   
   // Option 2: Add custom extensions
   opts := topics.Options{
       Extensions: []string{".txt", ".md", ".txxt", ".rst"},
   }
   if err := topics.InitializeWithOptions(rootCmd, "cmd/myapp/topics", opts); err != nil {
       log.Debug().Err(err).Msg("Failed to initialize topics")
   }

4. Users can now access help topics:

   $ myapp help dry-run        # Finds option-dry-run.txt
   $ myapp help architecture   # Finds architecture.md
   $ myapp help topics         # Lists all available topics

Topic Files
-----------

Default supported extensions:
• .txt - Plain text files
• .md - Markdown files

You can add more extensions (like .txxt, .rst, .adoc) using InitializeWithOptions.

Naming Conventions:
• option-<flag>.<ext> - For flag/option documentation (e.g., option-dry-run.txt)
• <topic>.<ext> - For general topics (e.g., architecture.md)

The option- prefix allows users to access flag help naturally:
• "help dry-run" finds option-dry-run.txt
• "help --dry-run" also finds option-dry-run.txt

Example Integration
-------------------

See dodot's integration in internal/cli/commands.go for a complete example
that searches multiple paths for help topics.

Best Practices
--------------

• Keep topic files concise and focused
• Use consistent formatting across topics
• Include examples in topic files
• Name files after the flags/concepts they explain
• Consider subdirectories for organization

Testing
-------

The package includes comprehensive tests. Run with:

$ go test ./pkg/cobrax/topics/...

Future Enhancements
-------------------

• Markdown rendering for terminal display
• Topic categories and grouping
• Multi-language support
• Topic search functionality