ZERG Document

ZERG Document

Generate documentation for a specific component, module, or command.

Usage

/zerg:document <target> [--type auto|module|command|config|api|types]
                        [--output PATH]
                        [--depth shallow|standard|deep]
                        [--update]
                        [--tone educational|reference|tutorial]

Arguments

• <target>: Path to file or module to document (required)

Flags

• --type: Component type override. Default: auto (uses ComponentDetector)
  • auto - Auto-detect from file structure
  • module - Python module documentation
  • command - ZERG command file documentation
  • config - Configuration file documentation
  • api - API endpoint documentation
  • types - Type definitions documentation
• --output: Output path for generated docs. Default: stdout
• --depth: Documentation depth. Default: standard
  • shallow - Public API only
  • standard - Public API + key internals
  • deep - Full documentation with examples
• --update: Update existing documentation in-place
• --tone: Documentation tone. Default: educational
  • educational - Concept-first with CONCEPT, NARRATIVE, DIAGRAM, COMMAND sections (default)
  • reference - Terse tables and API signatures for quick lookup
  • tutorial - Step-by-step walkthrough with simulated dialogues

Tone

The --tone flag controls the documentation style. Before generating documentation, read the tone definition file at zerg/data/tones/{tone}.md and follow its style guidelines, required sections, and output structure template.

Available tones:

• educational (default): Every concept gets CONCEPT, NARRATIVE, DIAGRAM, COMMAND sections. Teaches "why" not just "what".
• reference: Terse tables, API signatures, parameter lists. Quick lookup format.
• tutorial: Step-by-step walkthrough with numbered steps, expected output, and troubleshooting.

Pipeline

1. Detect: ComponentDetector identifies component type (or use --type override)
2. Extract: SymbolExtractor parses AST for classes, functions, imports, docstrings
3. Map: DependencyMapper resolves import relationships
4. Diagram: MermaidGenerator creates relevant diagrams
5. Render: DocRenderer applies type-specific template
6. Cross-ref: CrossRefBuilder injects glossary links and "See also" sections
7. Output: Write to --output path or stdout

Examples

# Auto-detect and document a module
/zerg:document zerg/launcher.py

# Document a command file explicitly
/zerg:document zerg/data/commands/zerg:rush.md --type command

# Deep documentation to file
/zerg:document zerg/doc_engine/extractor.py --depth deep --output docs/extractor.md

# Update existing docs
/zerg:document zerg/launcher.py --output docs/launcher.md --update

Depth Levels

Shallow

• Public classes and functions
• Parameter types and return types
• One-line descriptions

Standard

• Everything in shallow
• Key internal methods
• Import relationships
• Basic Mermaid diagram

Deep

• Everything in standard
• All methods including private
• Usage examples from codebase
• Full dependency graph
• Cross-references to related components

Task Tracking

On invocation, create a Claude Code Task to track this command:

Call TaskCreate:

• subject: "[Document] Generate docs: {target}"
• description: "Generating {depth} documentation for {target}. Type: {type}."
• activeForm: "Generating documentation"

Immediately call TaskUpdate:

• taskId: (the Claude Task ID)
• status: "in_progress"

On completion, call TaskUpdate:

• taskId: (the Claude Task ID)
• status: "completed"

Error Handling

• If target file not found: report error, suggest similar paths
• If AST parse fails: fall back to regex-based extraction with warning
• If type detection is ambiguous: use --type flag or prompt user

Help

When --help is passed in $ARGUMENTS, display usage and exit:

/zerg:document — Generate documentation for a specific component, module, or command.

Flags:
  --type auto|module|command|config|api|types
                    Component type override (default: auto)
  --output PATH     Output path for generated docs (default: stdout)
  --depth shallow|standard|deep
                    Documentation depth (default: standard)
  --update          Update existing documentation in-place
  --tone educational|reference|tutorial
                    Documentation tone (default: educational)
  --help            Show this help message