Documentation Generator Commands

doc [subcommand]

The main documentation generator command with multiple subcommands for different documentation needs.

Subcommands:

• doc docstring <file> [symbol] - Suggest docstrings for code
• doc readme [path] [out] - Generate README.md for project/directory
• doc readme <file> - Generate README.md for a specific file
• doc tutorial [out] - Generate tutorial from session history
• doc diagram <file> [symbol] [format] - Generate code architecture diagrams

Examples:

# Show help
doc
doc help

# Generate docstrings
doc docstring app.py

# Generate README
doc readme

# Generate tutorial
doc tutorial

# Generate diagram
doc diagram app.py

doc docstring <file> [symbol]

Generate high-quality docstring suggestions for functions, methods, classes, and modules in your code. Supports multiple programming languages with language-specific docstring styles.

Features:

• Language-specific docstring styles (Python triple-quoted, JSDoc for JS/TS, etc.)
• Function, method, class, and module documentation
• Optional symbol-specific documentation
• Idiomatic style for each language
• Shows function signatures with proposed docstrings
• Does not rewrite the entire file - focuses on documentation only

Supported Languages:

Automatically detects language and uses appropriate docstring style:

• Python: Triple-quoted docstrings
• JavaScript/TypeScript: JSDoc comments
• Java: JavaDoc comments
• Other languages: Appropriate comment styles

Parameters:

• file - Source file to generate docstrings for
• symbol - (Optional) Specific function/class name to document

Examples:

# Generate docstrings for entire file
doc docstring app.py

# Generate docstring for specific function/class
doc docstring app.py calculate_total
doc docstring app.py MyClass

# Generate for different languages
doc docstring server.js
doc docstring Main.java

Output Format:

For each function/class, shows:

• Function/class signature
• Proposed docstring beneath it
• Language-appropriate formatting

doc readme [path] [out]

Generate comprehensive README.md files for projects, directories, or individual files. Automatically analyzes project structure, health, and code to create professional documentation.

Modes:

• Project/Directory Mode: Analyzes entire project structure
• File Mode: Creates documentation for a single file/script

Project/Directory README Includes:

• Project title and short tagline
• Overview and description
• Features list
• Installation instructions
• Usage examples
• Dependencies (libraries, APIs)
• Configuration details
• Running tests (if applicable)
• Folder structure overview
• Security considerations
• Error handling and troubleshooting
• Contributing guidelines
• License placeholder (MIT-based)

File-Specific README Includes:

• Title and short description
• What the script/tool does
• Inputs (CLI args, env vars, config)
• Outputs and side effects
• Usage examples
• Dependencies
• Notes and limitations
• Internal architecture
• Security considerations
• Error handling and troubleshooting
• License details

Parameters:

• path - (Optional) Directory or file to analyze. Defaults to current directory (.)
• out - (Optional) Output file path. Defaults to README.generated.md for directories or filename.README.generated.md for files

Examples:

# Generate README for current directory
doc readme

# Generate README for specific directory
doc readme src/
doc readme /path/to/project

# Generate README for specific file
doc readme app.py

# Specify output file
doc readme . README.md
doc readme app.py app.README.md

Analysis Process:

For project/directory mode, the command:

1. Analyzes project structure using _analyze_project_structure()
2. Generates health report using _generate_health_report()
3. Collects representative code file samples (up to 5 files, 800 chars each)
4. Uses AI to generate comprehensive README based on analysis

doc tutorial [out]

Generate a step-by-step tutorial from your current session's command history. Automatically creates a tutorial that explains what you did, grouped into logical sections.

Features:

• Analyzes last 200 commands from session history
• Groups commands into logical sections
• Explains goals and purpose of each section
• Shows key commands with explanations
• Assumes reader starts from scratch
• Includes timestamps from command history

Parameters:

• out - (Optional) Output file path. Defaults to TUTORIAL.generated.md in current directory

Examples:

# Generate tutorial from current session
doc tutorial

# Specify output file
doc tutorial my-tutorial.md
doc tutorial docs/tutorial.md

Tutorial Structure:

Each section includes:

• Section heading
• Goal explanation
• Key commands used
• Explanation of what each command does and why

doc diagram <file> [symbol] [format]

Generate code architecture diagrams from source files. Creates visual representations of code structure, relationships, and data flow in multiple formats.

Features:

• Multiple diagram formats (Mermaid, PlantUML, Text/ASCII)
• Shows main entry points (e.g., main() function)
• Displays helper functions and data flow
• Highlights modules, classes, functions, and relationships
• Shows input flow (CLI args, config) to output
• Groups related functions/components logically
• Optional symbol-specific diagrams

Supported Formats:

• mermaid - Mermaid diagram format (default)
• plantuml - PlantUML diagram format
• text - ASCII/text diagram format

Parameters:

• file - Source file to generate diagram for
• symbol - (Optional) Specific function/class to focus on
• format - (Optional) Diagram format (mermaid, plantuml, text). Defaults to mermaid

Examples:

# Generate Mermaid diagram (default)
doc diagram app.py

# Generate PlantUML diagram
doc diagram app.py "" plantuml

# Generate text/ASCII diagram
doc diagram app.py "" text

# Focus on specific symbol
doc diagram app.py MyClass
doc diagram app.py process_data mermaid

# Different formats
doc diagram server.js "" mermaid
doc diagram Main.java "" plantuml

Output Files:

Diagrams are saved as:

• filename.diagram.mermaid.md for Mermaid format
• filename.diagram.plantuml.md for PlantUML format
• filename.diagram.txt for text format

Diagram Content:

The diagrams show:

• Main entry point function (e.g., main())
• Important helper functions
• Data flow between functions
• Module/class relationships
• Input flow (CLI args, config) to HTTP calls/I/O to output
• Logical grouping of related components