Documentation Automation Skill

When to Use

• 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

• 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

• 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

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

@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.
    ...
    """

### 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

• 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

• 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

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

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

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

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