AI Code Documentation Generator

Overview

This workflow automatically generates comprehensive documentation from codebases. It analyzes code structure, extracts public interfaces, generates documentation for each component, and deploys to documentation sites — saving developers hours of manual documentation work.

Difficulty

Easy — Requires basic setup of Claude API and Git/Filesystem MCP.

Tools Required

Tool	Purpose
Claude	Documentation generation
Git MCP	Repository access and history
Filesystem MCP	Code file reading
MkDocs	Static site generation
Notion	Optional: documentation storage

Workflow Steps

Step 1: Codebase Analysis

import os
from pathlib import Path

def analyze_codebase(repo_path: str) -> dict:
    """Analyze codebase structure."""
    
    structure = {
        "files": [],
        "directories": [],
        "languages": {},
        "dependencies": []
    }
    
    for root, dirs, files in os.walk(repo_path):
        for file in files:
            ext = Path(file).suffix
            structure["languages"][ext] = structure["languages"].get(ext, 0) + 1
            structure["files"].append(os.path.join(root, file))
    
    # Parse package.json, requirements.txt, etc.
    structure["dependencies"] = extract_dependencies(repo_path)
    
    return structure

Step 2: API Extraction

import ast
import inspect

def extract_public_api(file_path: str) -> list[dict]:
    """Extract public functions, classes, and interfaces."""
    
    with open(file_path) as f:
        tree = ast.parse(f.read())
    
    api_elements = []
    
    for node in ast.walk(tree):
        if isinstance(node, (ast.FunctionDef, ast.ClassDef)):
            if not node.name.startswith("_"):
                api_elements.append({
                    "name": node.name,
                    "type": "function" if isinstance(node, ast.FunctionDef) else "class",
                    "line": node.lineno,
                    "args": [arg.arg for arg in node.args.args] if isinstance(node, ast.FunctionDef) else None,
                    "decorators": [ast.unparse(d) for d in node.decorator_list]
                })
    
    return api_elements

Step 3: Documentation Generation

import anthropic

client = anthropic.Anthropic()

def generate_documentation(code_content: str, element: dict) -> str:
    """Generate documentation for a code element."""
    
    prompt = f"""
    Generate comprehensive documentation for this code element.
    
    Code:
    ```{get_language(element)}
    {code_content}
    ```
    
    Element: {element['name']} ({element['type']})
    
    Please provide:
    1. **Description**: What does this do?
    2. **Parameters**: For functions, describe each parameter
    3. **Returns**: What does it return?
    4. **Example**: A usage example
    5. **Notes**: Any important considerations
    
    Format as Markdown.
    """
    
    response = client.messages.create(
        model="claude-3-5-sonnet-20241022",
        max_tokens=1024,
        messages=[{"role": "user", "content": prompt}]
    )
    
    return response.content[0].text

Step 4: Example Generation

def generate_usage_examples(api_elements: list[dict], repo_path: str) -> dict:
    """Generate usage examples for each API element."""
    
    examples = {}
    
    for element in api_elements:
        # Read surrounding code for context
        file_path = element.get("file")
        with open(file_path) as f:
            lines = f.readlines()
        
        # Get context around the element
        start = max(0, element["line"] - 10)
        end = min(len(lines), element["line"] + 20)
        context = "".join(lines[start:end])
        
        prompt = f"""
        Generate a practical usage example for this code element.
        
        Context:
        ```
        {context}
        ```
        
        Element: {element['name']}
        
        Create a complete, runnable example that demonstrates:
        - How to import/use this element
        - Typical use case
        - Expected output
        """
        
        response = client.messages.create(
            model="claude-3-5-sonnet-20241022",
            max_tokens=512,
            messages=[{"role": "user", "content": prompt}]
        )
        
        examples[element["name"]] = response.content[0].text
    
    return examples

Step 5: Documentation Review

def review_documentation(docs: dict, codebase: dict) -> dict:
    """Review documentation for accuracy and completeness."""
    
    review_prompt = f"""
    Review this generated documentation against the codebase.
    
    Codebase structure:
    {codebase}
    
    Documentation to review:
    {docs}
    
    Check for:
    1. Accuracy: Does the documentation match the code?
    2. Completeness: Are all public APIs documented?
    3. Clarity: Is the documentation easy to understand?
    4. Examples: Are examples correct and runnable?
    
    Return a review report with any issues found.
    """
    
    response = client.messages.create(
        model="claude-3-5-sonnet-20241022",
        max_tokens=2048,
        messages=[{"role": "user", "content": review_prompt}]
    )
    
    return response.content[0].text

Step 6: Deployment

import subprocess

def deploy_documentation(docs: dict, output_dir: str):
    """Deploy documentation to MkDocs site."""
    
    # Create MkDocs structure
    os.makedirs(f"{output_dir}/docs/api", exist_ok=True)
    
    # Generate index page
    with open(f"{output_dir}/index.md", "w") as f:
        f.write(generate_index(docs))
    
    # Generate API docs
    for module, elements in docs.items():
        with open(f"{output_dir}/docs/api/{module}.md", "w") as f:
            f.write(generate_module_docs(module, elements))
    
    # Build and deploy
    subprocess.run(["mkdocs", "build", "-d", f"{output_dir}/site"])
    
    # Optional: Deploy to GitHub Pages
    subprocess.run(["mkdocs", "gh-deploy"])

Example Output

Generated Documentation Structure

docs/
├── index.md                    # Home page
├── api/
│   ├── core.md                 # Core module docs
│   ├── utils.md                # Utilities docs
│   └── models.md               # Data models docs
├── examples/
│   ├── quickstart.md           # Getting started
│   └── advanced.md             # Advanced patterns
└── contributing.md             # Contribution guide

Sample Documentation

# `process_data`

## Description

Processes raw data through a series of transformation pipelines.

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | `List[Dict]` | Yes | Raw data to process |
| `pipeline` | `str` | No | Pipeline name (default: "standard") |
| `validate` | `bool` | No | Enable validation (default: True) |

## Returns

`List[Dict]` - Processed data with added metadata.

## Example

```python
from mylib import process_data

result = process_data(
    data=[{"value": 1}, {"value": 2}],
    pipeline="standard",
    validate=True
)
# Returns: [{"value": 1, "processed": True}, ...]

Notes

• Validation adds ~10% overhead
• Pipeline must be registered before use

## Pros

- ✅ Saves hours of manual documentation
- ✅ Consistent documentation format
- ✅ Always up-to-date with code changes
- ✅ Includes usage examples
- ✅ Multi-language support

## Cons

- ❌ May miss edge cases in complex code
- ❌ Requires review for accuracy
- ❌ Initial setup time for new codebases
- ❌ May generate verbose documentation

## When to Use

- **New projects**: Auto-generate initial docs
- **Legacy codebases**: Document undocumented code
- **API libraries**: Keep API docs current
- **Team onboarding**: Help new developers understand code
- **Open source projects**: Maintain quality documentation

## Resources

- [MkDocs Documentation](https://www.mkdocs.org/)
- [Git MCP Server](https://github.com/modelcontextprotocol/servers/tree/main/src/git)
- [Filesystem MCP Server](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem)
- [Python AST Module](https://docs.python.org/3/library/ast.html)