gh-action-readme/CLAUDE.md

CLAUDE.md - Development Guide

gh-action-readme - CLI tool for GitHub Actions documentation generation

🚨 CRITICAL: README Protection

NEVER overwrite /README.md - The root README.md is the main project documentation.

For testing generation commands:

cd testdata/
../gh-action-readme gen [options]

🏗️ Architecture

Core Components:

• main.go - CLI with Cobra framework
• internal/generator.go - Core generation logic
• internal/config.go - Viper configuration (XDG compliant)
• internal/output.go - Colored terminal output
• internal/json_writer.go - JSON format support

Templates:

• templates/readme.tmpl - Default template
• templates/themes/ - Theme-specific templates
  • github/ - GitHub-style with badges
  • gitlab/ - GitLab CI/CD focused
  • minimal/ - Clean, concise
  • professional/ - Comprehensive with ToC
  • asciidoc/ - AsciiDoc format

🛠️ Commands & Usage

Available Commands:

gh-action-readme gen [flags]          # Generate documentation
gh-action-readme validate            # Validate action.yml files
gh-action-readme config {init|show|themes}  # Configuration management
gh-action-readme version             # Show version
gh-action-readme about               # About tool

Key Flags:

• --theme - Select template theme
• --output-format - Choose format (md, html, json, asciidoc)
• --recursive - Process directories recursively
• --verbose - Detailed output
• --quiet - Suppress output

🔧 Development Workflow

Build: go build . Test: go test ./internal Lint: golangci-lint run

Testing Generation (SAFE):

cd testdata/example-action/
../../gh-action-readme gen --theme github

📊 Feature Matrix

Feature	Status	Files
CLI Framework	✅	main.go
File Discovery	✅	generator.go:174
Template Themes	✅	templates/themes/
Output Formats	✅	generator.go:67-78
Validation	✅	internal_validator.go
Configuration	✅	config.go
Colored Output	✅	output.go

🎨 Themes

Available Themes:

1. default - Original simple template
2. github - Badges, tables, collapsible sections
3. gitlab - GitLab CI/CD examples
4. minimal - Clean, concise documentation
5. professional - Comprehensive with troubleshooting

📄 Output Formats

Supported Formats:

• md - Markdown (default)
• html - HTML with styling
• json - Structured data for APIs
• asciidoc - Technical documentation format

🧪 Testing Strategy

Unit Tests: internal/*_test.go (26.2% coverage) Integration: Manual CLI testing Templates: Test with testdata/example-action/

Test Commands:

# Core functionality
cd testdata/ && ../gh-action-readme gen

# All themes
for theme in github gitlab minimal professional; do
  cd testdata/ && ../gh-action-readme gen --theme $theme
done

# All formats
for format in md html json asciidoc; do
  cd testdata/ && ../gh-action-readme gen --output-format $format
done

🚀 Production Features

Configuration:

• XDG Base Directory compliant
• Environment variable support
• Theme persistence
• Multiple search paths

Error Handling:

• Colored error messages
• Actionable suggestions
• Context-aware validation
• Graceful fallbacks

Performance:

• Progress bars for batch operations
• Binary-relative template paths
• Efficient file discovery
• Minimal dependencies

🔄 Adding New Features

New Theme:

1. Create templates/themes/THEME_NAME/readme.tmpl
2. Add to resolveThemeTemplate() in config.go:67
3. Update configThemesHandler() in main.go:284

New Output Format:

1. Add constant to generator.go:14
2. Add case to GenerateFromFile() switch generator.go:67
3. Implement generate[FORMAT]() method
4. Update CLI help in main.go:84

New Template Functions: Add to templateFuncs() in internal_template.go:19

---

Status: PRODUCTION READY ✅ All core features implemented and tested.