Documentation Automation System¶

Gira includes a comprehensive documentation automation system that keeps CLI reference documentation synchronized with code changes automatically.

🎯 Overview¶

The documentation automation system provides:

Automatic CLI reference generation from command definitions
Git hooks that regenerate docs when CLI code changes
Multiple documentation formats (CLI reference, AI agent guides, workflows)
Live API documentation via MkDocs mkdocstrings plugin
Convenient scripts for manual documentation management

🔧 Components¶

1. Core Documentation Generation¶

Gira's built-in documentation generation system supports multiple output formats:

# Generate CLI reference (default)
gira docs generate --output docs/05-reference/cli-reference.md

# Generate AI agent documentation
gira docs generate --type agents --output docs/06-development/ai-agent-guides-generated/agents.md

# Generate workflow documentation
gira docs generate --type workflow --output docs/02-user-guide/workflows-generated/workflows.md

# Generate all documentation types
gira docs generate --type all

2. Git Hooks Automation¶

The system includes git hooks that automatically regenerate documentation when CLI code changes:

Pre-commit Hook¶

Detects changes to src/gira/cli/ files
Automatically regenerates CLI reference and AI agent documentation
Stages updated documentation files for commit

Post-merge Hook¶

Regenerates documentation after merging CLI changes
Notifies developer to commit updated documentation

Installation¶

# Install git hooks for current repository
./scripts/install-git-hooks.sh

# Or use the convenience script from pyproject.toml
python -m tools.scripts install-hooks

3. MkDocs Integration¶

Enhanced MkDocs configuration with:

mkdocstrings plugin for live API documentation
Static CLI reference at docs/05-reference/cli-reference.md
Live API reference at docs/05-reference/api-reference.md
Generated documentation integrated into navigation

4. Convenience Scripts¶

Multiple automation scripts available via pyproject.toml:

# Individual generation commands
python -m tools.scripts docs-generate
python -m tools.scripts docs-generate-full
python -m tools.scripts docs-generate-agents
python -m tools.scripts docs-generate-workflows
python -m tools.scripts docs-generate-commands  # NEW: Individual command pages

# MkDocs operations
python -m tools.scripts docs-serve
python -m tools.scripts docs-build
python -m tools.scripts docs-deploy

# Complete workflow
python -m tools.scripts docs-full-rebuild

5. Individual Command Documentation¶

Enhanced documentation system now generates detailed individual command pages:

# Generate detailed docs for all major commands
./scripts/generate-command-docs.sh

# Generate docs for specific command
gira docs generate --command "ticket create" --template command.md.j2 --output docs/05-reference/commands/ticket-create.md

Individual Command Pages Include: - Complete argument details with types and validation - All options with choices, defaults, and examples
- Usage patterns and real-world examples - Cross-references to related commands - Rich formatting optimized for MkDocs

🚀 Usage Guide¶

For Developers¶

Daily Development¶

When making changes to CLI commands, the automation system works transparently:

Make CLI changes to files in src/gira/cli/
Commit changes normally with git commit
Documentation automatically updates via pre-commit hook
Updated docs are staged and included in your commit

Skipping Documentation Generation¶

Sometimes you may want to commit CLI changes without regenerating documentation:

# Skip documentation generation for this commit
GIRA_SKIP_DOCS=1 git commit -m "WIP: experimental CLI changes"

# Normal commit with documentation generation
git commit -m "feat: add new search command"

Manual Documentation Updates¶

Sometimes you may want to regenerate documentation manually:

# Update just CLI reference
gira docs generate --output docs/05-reference/cli-reference.md

# Update everything and build site
./scripts/update-docs.sh

# Build and serve locally
mkdocs serve

Working with Generated Documentation¶

Static files: docs/05-reference/cli-reference.md - Complete CLI reference
Generated guides: docs/06-development/ai-agent-guides-generated/ - AI agent documentation
Workflow docs: docs/02-user-guide/workflows-generated/ - Workflow documentation
Live API docs: Available in MkDocs site at API Reference section

For New Contributors¶

Setup¶

# 1. Install development dependencies
pip install -e ".[docs,dev]"

# 2. Install git hooks
./scripts/install-git-hooks.sh

# 3. Test documentation build
mkdocs serve

Understanding the System¶

Don't manually edit generated documentation files
CLI reference stays synchronized automatically with code changes
Live API docs update automatically when you build the site
Navigation is maintained automatically for generated content

🔍 Troubleshooting¶

Git Hooks Not Working¶

# Reinstall hooks
./scripts/install-git-hooks.sh

# Check hook permissions
ls -la .git/hooks/pre-commit .git/hooks/post-merge

# Test hook manually
.git/hooks/pre-commit

Documentation Build Failures¶

# Check for missing dependencies
pip install -e ".[docs]"

# Rebuild documentation from scratch
./scripts/update-docs.sh

# Test MkDocs build
mkdocs build --strict

API Reference Issues¶

If the live API reference shows import errors: 1. Ensure modules exist in src/gira/ 2. Update docs/05-reference/api-reference.md to use correct module paths 3. Check that modules have proper docstrings

Generated Content Missing¶

# Regenerate all documentation types
gira docs generate --type all

# Force regeneration of specific type
gira docs generate --type agents --output docs/06-development/ai-agent-guides-generated/agents.md

📝 Maintenance¶

Adding New Documentation Types¶

To add a new documentation type:

Create template in src/gira/templates/
Update CLI command in gira docs generate
Add to automation scripts in pyproject.toml
Update git hooks if needed
Add to MkDocs navigation in mkdocs.yml

When adding new generated documentation:

Generate the documentation using appropriate command
Add to mkdocs.yml navigation section
Test MkDocs build with mkdocs build
Commit navigation changes along with generated content

🎉 Benefits¶

This automation system provides:

Zero-maintenance documentation - stays synchronized automatically
Consistent formatting - all documentation follows templates
Developer-friendly workflow - no manual intervention required
Multiple output formats - CLI reference, AI guides, workflows
Live API documentation - always current with source code
Professional presentation - Material theme with search and navigation

The system ensures that Gira's documentation always reflects the current state of the CLI, providing users and AI agents with accurate, up-to-date reference material.