docgen - Documentation Generator¶
Automated documentation generation tool for codebases, APIs, and projects.
Overview¶
docgen analyzes source code and generates comprehensive documentation including API references, code documentation, dependency diagrams, and usage guides. It supports multiple programming languages and output formats.
When to use: Generating documentation for projects, creating API references, or maintaining up-to-date code documentation.
Usage¶
docgen [options] <source-path> [output-path]
```bash
### Options
- `-o DIR`: Output directory (default: ./docs)
- `-f FORMAT`: Output format (html, markdown, pdf)
- `-l LANG`: Source language (auto-detect if not specified)
- `-t TYPE`: Documentation type (api, code, full)
- `-c CONFIG`: Configuration file
- `-v`: Verbose output
- `-q`: Quiet mode
- `-h`: Show help
### Documentation Types
- `api`: API reference documentation
- `code`: Code documentation with comments
- `full`: Complete documentation package
- `diagrams`: Generate dependency and architecture diagrams
## Examples
### Basic Documentation
```bash
# Generate docs for current directory
docgen .
# Specify output directory
docgen -o ./docs .
# Generate API docs only
docgen -t api -o api-docs src/
```bash
### Language-Specific
```bash
# Python project
docgen -l python -o docs src/
# JavaScript/Node.js
docgen -l javascript -o docs lib/
# Go project
docgen -l go -o docs .
```bash
### Output Formats
```bash
# HTML documentation
docgen -f html -o docs .
# Markdown files
docgen -f markdown -o docs .
# PDF documentation
docgen -f pdf -o docs .
```bash
### Advanced Usage
```bash
# Full documentation with diagrams
docgen -t full -f html -o docs .
# Custom configuration
docgen -c docgen.toml -o docs .
# Verbose output
docgen -v -o docs src/
```bash
## How It Works
### Analysis Pipeline
1. **Code Parsing**: Analyze source files and extract structure
2. **Documentation Extraction**: Parse comments and docstrings
3. **Dependency Analysis**: Build dependency graphs
4. **Content Generation**: Create documentation pages
5. **Cross-Referencing**: Link related documentation
6. **Output Rendering**: Generate final documentation
### Supported Languages
#### Python
- **Docstrings**: Google/NumPy/Sphinx formats
- **Type Hints**: Type annotation documentation
- **Modules**: Package and module documentation
- **Classes/Functions**: Detailed API documentation
#### JavaScript/Node.js
- **JSDoc**: Standard JSDoc comment parsing
- **ES6 Modules**: Import/export documentation
- **Classes**: Class and method documentation
- **TypeScript**: Type definition documentation
#### Go
- **Godoc**: Standard Go documentation
- **Packages**: Package documentation
- **Functions/Types**: API documentation
- **Interfaces**: Interface documentation
#### Other Languages
- **Rust**: Documentation comment parsing
- **Java**: Javadoc parsing
- **C/C++**: Doxygen comment parsing
- **Ruby**: RDoc parsing
## Configuration
### Configuration File
```toml
# docgen.toml
[project]
name = "My Project"
version = "1.0.0"
description = "Project description"
author = "Author Name"
[documentation]
type = "full"
format = "html"
theme = "default"
[source]
language = "python"
paths = ["src/", "lib/"]
exclude = ["test_*", "__pycache__"]
[output]
directory = "./docs"
clean = true
index_file = "index.html"
[parsing]
extract_private = false
include_examples = true
parse_comments = true
[diagrams]
enabled = true
format = "svg"
engine = "graphviz"
```bash
### Environment Variables
```bash
# Output settings
export DOCGEN_OUTPUT_DIR="./docs"
export DOCGEN_FORMAT="markdown"
# Parsing options
export DOCGEN_LANGUAGE="python"
export DOCGEN_EXTRACT_PRIVATE="false"
# Theme and styling
export DOCGEN_THEME="dark"
export DOCGEN_CSS="custom.css"
```bash
## Dependencies
### Required
- **Python**: Core processing (if using Python version)
- **bash**: Shell execution
- **find**: File discovery
- **grep/awk**: Text processing
### Optional
- **pandoc**: Format conversion
- **graphviz**: Diagram generation
- **plantuml**: UML diagram creation
- **doxygen**: C/C++ documentation
- **sphinx**: Python documentation
- **jsdoc**: JavaScript documentation
## Troubleshooting
### No Documentation Generated
**Symptom:** Empty output directory
**Cause:** No recognizable code or documentation comments
**Fix:**
```bash
# Check source files
find src/ -name "*.py" | head -5
# Add docstrings/comments
# Example Python:
def my_function():
"""Function description"""
pass
# Run with verbose
docgen -v -o docs .
```bash
### Incorrect Language Detection
**Symptom:** Wrong language detected or parsing errors
**Cause:** Mixed languages or unusual file extensions
**Fix:**
```bash
# Specify language explicitly
docgen -l python -o docs .
# Check file extensions
find . -name "*.*" | sort | uniq -c
# Update configuration
# Edit docgen.toml
[source]
language = "python"
```bash
### Missing Dependencies
**Symptom:** Errors about missing tools
**Cause:** Optional dependencies not installed
**Fix:**
```bash
# Install common tools
sudo apt install graphviz plantuml pandoc
# Python specific
pip install sphinx sphinx-rtd-theme
# JavaScript specific
npm install -g jsdoc
# Check tool availability
docgen --check-tools
```bash
### Large Output
**Symptom:** Documentation very large or slow to generate
**Cause:** Large codebase or detailed analysis
**Fix:**
```bash
# Limit scope
docgen -t api -o docs src/main/
# Exclude test files
export DOCGEN_EXCLUDE="test_*,*_test.py"
# Use basic type
docgen -t code -o docs .
```bash
## Performance
### Generation Times
| Project Size | Language | Time | Output Size |
| ---------------- | ---------- | ----- | ----------- |
| Small (<1K LOC) | Python | 10s | 2MB |
| Medium (10K LOC) | JavaScript | 2min | 15MB |
| Large (100K LOC) | Go | 10min | 50MB |
### Resource Usage
- **Memory**: 100-500MB depending on project size
**CPU**: 50-80% during analysis
- **Disk**: Output size + temporary files
## Integration
### With Build Systems
```bash
# Makefile integration
docs:
docgen -o docs .
# package.json script
"scripts": {
"docs": "docgen -o docs ."
}
# CI/CD pipeline
- name: Generate docs
run: docgen -o docs .
```bash
### With Version Control
```bash
# Pre-commit hook
docgen -q -o docs . && git add docs/
# GitHub Pages deployment
docgen -f html -o docs .
git checkout gh-pages
cp -r docs/* .
git commit -m "Update documentation"
```bash
### With Development Workflow
```bash
# Auto-generate on file change
find src/ -name "*.py" | entr docgen -q -o docs .
# Documentation server
cd docs && python -m http.server 8000
# Check documentation coverage
docgen --coverage -o docs .
```bash
### With IDEs
```bash
# VS Code task
{
"label": "Generate Documentation",
"type": "shell",
"command": "docgen",
"args": ["-o", "docs", "."],
"group": "build"
}
```bash
## Output Structure
```bash
docs/
├── index.html # Main documentation page
├── api/ # API reference
│ ├── modules.html
│ ├── classes.html
│ └── functions.html
├── code/ # Code documentation
│ ├── source/
│ └── comments/
├── diagrams/ # Generated diagrams
│ ├── dependencies.svg
│ └── architecture.png
├── examples/ # Usage examples
├── search.html # Search functionality
├── css/ # Stylesheets
├── js/ # JavaScript
└── assets/ # Images and resources
```bash
## Technical Details
### Parsing Engines
#### Python
```python
# Docstring extraction
def parse_docstring(node):
"""Extract and parse Python docstrings"""
docstring = ast.get_docstring(node)
return parse_google_format(docstring)
```bash
#### JavaScript
```javascript
// JSDoc parsing
/**
* @param {string} name - User name
* @returns {Object} User object
*/
function getUser(name) {
// Implementation
}
```bash
#### Go
```go
// Godoc parsing
// Package main provides the main application logic
package main
// GetUser retrieves a user by ID
func GetUser(id int) (*User, error) {
// Implementation
}
```bash
### Documentation Generation
- **Templates**: Jinja2/Handlebars for HTML generation
- **Markdown**: Direct markdown file generation
- **PDF**: Pandoc conversion from HTML/Markdown
- **Cross-references**: Automatic linking between pages
### Diagram Generation
- **Dependencies**: Graphviz DOT language
- **Architecture**: PlantUML diagrams
- **Class Diagrams**: UML class relationships
- **Flow Charts**: Process and data flows
### Search and Navigation
- **Index Generation**: Full-text search index
- **Cross-references**: Automatic linking
- **Table of Contents**: Hierarchical navigation
- **Breadcrumb Navigation**: Page location tracking
## See Also
- **[aicontext](aicontext.md)** - AI context generation
- **[scaffold](scaffold.md)** - Project scaffolding
- **[Documentation Guide](../../README.md#documentation)** - Documentation best practices