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:

• Scan backend/routers/**/*.py for route decorators

• Extract endpoint metadata:

• HTTP method (GET, POST, etc.)

• Path pattern

• Function name and docstring

• Parameters (path, query, body)

• Response model

• Tags

• Parse FastAPI models for request/response schemas

• Generate MDX file with:

• Endpoint description from docstring

• Request/response examples

• Parameter documentation

• Error codes

• 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

• Detect Changes: Analyze git diff or file changes

• Identify Impact: Determine which documentation needs updating

• Generate Updates: Create or update relevant documentation files

• Validate: Check documentation for completeness and accuracy

• Sync: Ensure all documentation locations are in sync

Usage Examples

Automatic API Documentation

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

• Detect the new route decorator using AST parsing

• 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

• Parse request/response models:

• Extract field names and types

• Generate JSON examples

• Document required vs optional fields

• Generate MDX documentation file:

• Create docs/api-reference/endpoint/{endpoint_name}.mdx

• Include description, parameters, examples

• Add to API reference index

• Update .cursor/API_REFERENCE.md with new endpoint

• 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:

• Detect new module structure

• Update architecture documentation

• Generate/update Mermaid diagrams

• 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:

• Parse Router Files: Use AST to parse Python files and extract route decorators

• Extract Metadata: Get method, path, parameters, response models from decorators

• Parse Docstrings: Extract endpoint descriptions from function docstrings

• Generate Examples: Create request/response examples from Pydantic models

• Generate MDX: Create MDX files following documentation standards

• 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