Documentation Automation Skill

Automate documentation updates to keep docs in sync with code changes.

When to Use

Use this skill when:

• API endpoints are added, modified, or removed
• Functions or classes are significantly changed
• Architecture changes occur
• New features are implemented
• Breaking changes are introduced

Capabilities

1. Detect Code Changes

Automatically detect changes that require documentation updates:

• Monitor backend/routers/**/*.py for API endpoint changes
• Monitor backend/utils/**/*.py for function/class changes
• Monitor architecture files for structural changes
• Use git diff to identify what changed

2. Generate API Reference

Automatically generate API reference documentation:

• Extract endpoint information from FastAPI routers
• Parse route decorators (@router.get, @router.post, etc.)
• Extract function docstrings for endpoint descriptions
• Parse request/response models from type hints
• Extract query parameters, path parameters, and request bodies
• Generate MDX documentation files with examples
• Update .cursor/API_REFERENCE.md
• Update docs/api-reference/endpoint/*.mdx
• Update docs/doc/developer/api/*.mdx

Process:

1. Scan backend/routers/**/*.py for route decorators
2. Extract endpoint metadata:
   • HTTP method (GET, POST, etc.)
   • Path pattern
   • Function name and docstring
   • Parameters (path, query, body)
   • Response model
   • Tags
3. Parse FastAPI models for request/response schemas
4. Generate MDX file with:
   • Endpoint description from docstring
   • Request/response examples
   • Parameter documentation
   • Error codes
5. Update API reference index

Example:

@router.post("/v1/conversations", response_model=CreateConversationResponse, tags=['conversations'])
def process_in_progress_conversation(
    request: ProcessConversationRequest = None, 
    uid: str = Depends(auth.get_current_user_uid)
):
    """
    Process an in-progress conversation after recording is complete.
    ...
    """

Generates:

### Process In-Progress Conversation

`POST /v1/conversations`

Process an in-progress conversation after recording is complete.

**Request Body**: ProcessConversationRequest (optional)

**Response**: CreateConversationResponse

3. Update Architecture Diagrams

Generate and update architecture diagrams:

• Analyze code structure to generate Mermaid diagrams
• Update .cursor/ARCHITECTURE.md with new components
• Update .cursor/DATA_FLOW.md if data flows change
• Update component documentation files

4. Sync Documentation

Keep documentation synchronized:

• Sync between .cursor/ internal docs and docs/ external docs
• Ensure consistency across documentation locations
• Update cross-references and links
• Validate documentation structure

Workflow

1. Detect Changes: Analyze git diff or file changes
2. Identify Impact: Determine which documentation needs updating
3. Generate Updates: Create or update relevant documentation files
4. Validate: Check documentation for completeness and accuracy
5. Sync: Ensure all documentation locations are in sync

Usage Examples

Automatic API Documentation

When a new endpoint is added to backend/routers/conversations.py:

1. Detect the new route decorator using AST parsing
2. Extract endpoint details:
   • Method from decorator (@router.post → POST)
   • Path from decorator argument
   • Function docstring for description
   • Parameters from function signature
   • Response model from response_model argument
3. Parse request/response models:
   • Extract field names and types
   • Generate JSON examples
   • Document required vs optional fields
4. Generate MDX documentation file:
   • Create docs/api-reference/endpoint/{endpoint_name}.mdx
   • Include description, parameters, examples
   • Add to API reference index
5. Update .cursor/API_REFERENCE.md with new endpoint
6. Validate documentation format and links

Parsing FastAPI Routers

Implementation approach:

import ast
from typing import List, Dict

def parse_fastapi_router(file_path: str) -> List[Dict]:
    """Parse FastAPI router file and extract endpoint information."""
    with open(file_path) as f:
        tree = ast.parse(f.read())
    
    endpoints = []
    for node in ast.walk(tree):
        if isinstance(node, ast.FunctionDef):
            # Check for route decorators
            for decorator in node.decorator_list:
                if isinstance(decorator, ast.Call):
                    # Extract @router.post("/path", ...)
                    method = get_decorator_method(decorator)
                    path = get_decorator_path(decorator)
                    response_model = get_response_model(decorator)
                    
                    endpoints.append({
                        'method': method,
                        'path': path,
                        'function_name': node.name,
                        'docstring': ast.get_docstring(node),
                        'parameters': parse_parameters(node),
                        'response_model': response_model,
                    })
    return endpoints

Architecture Update

When a new module is added:

1. Detect new module structure
2. Update architecture documentation
3. Generate/update Mermaid diagrams
4. Update component references

Related Resources

Rules

• .cursor/rules/documentation-standards.mdc - Documentation standards
• .cursor/rules/auto-documentation.mdc - Auto-documentation rules
• .cursor/rules/backend-api-patterns.mdc - API patterns

Subagents

• .cursor/agents/docs-generator.md - Documentation generation subagent

Commands

• /auto-docs - Trigger automatic documentation update
• /update-api-docs - Update API reference documentation from FastAPI routers
• /docs - Generate or update documentation

Implementation Notes

FastAPI Router Parsing

To auto-generate API docs:

1. Parse Router Files: Use AST to parse Python files and extract route decorators
2. Extract Metadata: Get method, path, parameters, response models from decorators
3. Parse Docstrings: Extract endpoint descriptions from function docstrings
4. Generate Examples: Create request/response examples from Pydantic models
5. Generate MDX: Create MDX files following documentation standards
6. Update Index: Add new endpoints to API reference index

Tools and Libraries

• AST: Python's Abstract Syntax Tree for parsing Python code
• Pydantic: Extract model schemas for request/response examples
• FastAPI: Use FastAPI's OpenAPI schema generation capabilities
• MDX: Generate MDX files with proper frontmatter and formatting

Automation Triggers

• Git Hooks: Run on commit if router files changed
• CI/CD: Run in CI pipeline to validate docs are up to date
• Manual: Use /update-api-docs command when needed