Skip to content

Automated Documentation Generation - Phase 1 Implementation

Status: ✅ COMPLETE Date: 2026-02-09 Related Proposal: proposals/automated-documentation-generation.md

Summary

Implemented Phase 1 of automated documentation generation from action metadata. The system generates markdown tables and summaries directly from registered action handlers, ensuring documentation stays in sync with code.

Implementation

Core Components

1. Generator Package (internal/docgen/)

generator.go - Core generator interface: - Generator struct with version and timestamp - GenerateSection() - main entry point for generating docs - getActions() - retrieves sorted list of all registered actions - platformSupported() - checks if action supports a platform

markdown.go - Markdown formatters: - generatePlatformMatrix() - platform support table - generateCapabilities() - action capabilities table (dry-run, become, check) - generateActionSummary() - detailed action summaries grouped by category

2. CLI Command (cmd/docs.go)

mooncake docs generate [flags]

Flags: - --section, -s - Section to generate (platform-matrix, capabilities, action-summary, all) - --output, -o - Output file (default: stdout) - --dry-run - Preview without writing files

3. Tests (internal/docgen/generator_test.go)

Comprehensive test suite covering: - Generator creation - All three section types - Section dispatcher - Error handling - Utility functions

Test Results: ✅ All 7 tests passing

Usage Examples

Generate Platform Matrix

mooncake docs generate --section platform-matrix

Output: 

<!-- Generated by mooncake docs generate -->
<!-- Version: dev | Generated: 2026-02-09 15:44:18 CET -->

| Action | Linux | macOS | Windows | FreeBSD |
|--------|-------|-------|-------|---------|
| assert | ✓ | ✓ | ✓ | ✓ |
| command | ✓ | ✓ | ✓ | ✓ |
| service | ✓ | ✓ | ✓ | ✗ |
...

Generate Action Capabilities

mooncake docs generate --section capabilities

Output: 

| Action | Category | Dry-Run | Become | Check Mode |
|--------|----------|---------|--------|------------|
| assert | system | Yes | No | No |
| command | command | Yes | Yes | No |
| shell | command | Yes | Yes | No |
...

Generate All Sections

mooncake docs generate --section all --output docs-next/generated/actions.md

Generates complete documentation (242 lines) with: - Platform Support Matrix - Action Capabilities - Action Summary (grouped by category)

Benefits Achieved

1. No More Manual Sync Issues

  • Documentation generated from source of truth (action metadata)
  • Impossible to show incorrect platform support or capabilities
  • Changes to actions automatically reflected in docs

2. Validation Ready

  • Generated output includes metadata comments with version and timestamp
  • Can be integrated into CI to catch stale docs
  • Diff detection easy with standardized format

3. Reduced Maintenance

  • Adding new action = documentation automatically included
  • Changing action metadata = docs automatically update
  • No manual table updates needed

4. Consistent Format

  • All tables use same structure
  • Alphabetically sorted for predictability
  • Clear generation markers for tracking

Files Created

internal/docgen/
├── generator.go           # Core generator (89 lines)
├── generator_test.go      # Test suite (212 lines)
└── markdown.go            # Markdown formatters (131 lines)

cmd/
└── docs.go                # CLI command (84 lines)

docs-next/development/
└── automated-docs-phase1.md  # This file

Files Modified

cmd/mooncake.go            # Added docsCommand() to commands list
cmd/cmd_test.go            # Updated test to expect 7 commands

Integration Points

Action Registry

  • Uses actions.List() to get all registered handlers
  • Accesses ActionMetadata struct for each action
  • No changes needed to existing action handlers

CLI Framework

  • Follows existing pattern (similar to presetsCommand())
  • Uses urfave/cli/v2 for flag handling
  • Consistent help text and error messages

Next Steps (Phase 2+)

Based on original proposal:

Phase 2: Extended Features

  • Template support for custom output formats
  • Multiple output formats (HTML, JSON schema)
  • Preset example generation from actual preset files
  • Schema documentation from Go structs

Phase 3: CI Integration

  • Add make docs target
  • CI check for stale docs
  • Auto-commit updated docs in CI
  • GitHub Actions workflow

Phase 4: Advanced Features

  • Multi-format output (HTML, PDF, man pages)
  • Interactive docs with live metadata API
  • Validation rules (missing descriptions, required examples)
  • Internationalization support

Validation

Manual Testing

# Build and test
go build -o mooncake ./cmd/
./mooncake docs generate --section platform-matrix
./mooncake docs generate --section capabilities
./mooncake docs generate --section action-summary
./mooncake docs generate --section all --output test.md

# Output file created: 242 lines, well-formatted markdown

Automated Testing

# Run all tests
go test ./internal/docgen/... -v
# PASS: 7/7 tests

# Run full test suite
make test
# PASS: All tests (including new tests)

Success Metrics

  • ✅ Zero manual table maintenance - Tables generated from code
  • ✅ Consistent format - All actions use same structure
  • ✅ Fast generation - Completes in milliseconds
  • ✅ Test coverage - Comprehensive test suite
  • ✅ Easy to use - Simple CLI interface
  • ✅ Extensible - Easy to add new section types

Conclusion

Phase 1 successfully implements the core documentation generation infrastructure. The system is production-ready and immediately useful for maintaining action documentation. The foundation is solid for extending to preset examples, schema docs, and CI integration in future phases.

The implementation solves the immediate problem that sparked this work: documentation getting out of sync with implementation (preset: wrapper issue). With this system, such discrepancies become impossible for generated content.