Back to Details

docs-automation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Documentation Automation Skill

文档自动化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
在以下场景中使用本Skill：
  • 添加、修改或移除API端点时
  • 函数或类发生重大变更时
  • 架构发生变更时
  • 实现新功能时
  • 引入破坏性变更时

Capabilities

核心能力

1. Detect Code Changes

1. 代码变更检测

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
自动检测需要更新文档的代码变更：
  • 监控
    backend/routers/**/*.py
    目录下的API端点变更
  • 监控
    backend/utils/**/*.py
    目录下的函数/类变更
  • 监控架构文件的结构变更
  • 使用git diff识别具体变更内容

2. Generate API Reference

2. API参考文档生成

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:
python
@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:
mdx
undefined
自动生成API参考文档：
  • 从FastAPI路由中提取端点信息
  • 解析路由装饰器（
    @router.get
    、
    @router.post
    等）
  • 提取函数文档字符串作为端点描述
  • 从类型提示中解析请求/响应模型
  • 提取查询参数、路径参数和请求体
  • 生成带示例的MDX文档文件
  • 更新
    .cursor/API_REFERENCE.md
    文件
  • 更新
    docs/api-reference/endpoint/*.mdx
    文件
  • 更新
    docs/doc/developer/api/*.mdx
    文件
流程：
  1. 扫描
    backend/routers/**/*.py
    文件中的路由装饰器
  2. 提取端点元数据：
    • HTTP方法（GET、POST等）
    • 路径模式
    • 函数名称和文档字符串
    • 参数（路径、查询、请求体）
    • 响应模型
    • 标签
  3. 解析FastAPI模型以获取请求/响应Schema
  4. 生成包含以下内容的MDX文件：
    • 来自文档字符串的端点描述
    • 请求/响应示例
    • 参数文档
    • 错误码
  5. 更新API参考文档索引
示例：
python
@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.
    ...
    """
生成的文档内容：
mdx
undefined

Process In-Progress Conversation

Process In-Progress Conversation

POST /v1/conversations
Process an in-progress conversation after recording is complete.
Request Body: ProcessConversationRequest (optional)
Response: CreateConversationResponse
undefined
POST /v1/conversations
Process an in-progress conversation after recording is complete.
Request Body: ProcessConversationRequest (optional)
Response: CreateConversationResponse
undefined

3. Update Architecture Diagrams

3. 架构图更新

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
生成并更新架构图：
  • 分析代码结构以生成Mermaid图
  • 在
    .cursor/ARCHITECTURE.md
    中新增组件信息
  • 若数据流发生变更，更新
    .cursor/DATA_FLOW.md
  • 更新组件文档文件

4. Sync Documentation

4. 文档同步

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
保持文档同步：
  • 同步
    .cursor/
    内部文档与
    docs/
    外部文档
  • 确保不同位置的文档内容一致
  • 更新交叉引用与链接
  • 验证文档结构

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
  1. 变更检测：分析git diff或文件变更
  2. 影响评估：确定需要更新的文档内容
  3. 生成更新内容：创建或更新相关文档文件
  4. 验证：检查文档的完整性与准确性
  5. 同步：确保所有位置的文档保持一致

Usage Examples

使用示例

Automatic API Documentation

自动生成API文档

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
当在
backend/routers/conversations.py
中添加新端点时：
  1. 使用AST解析检测新的路由装饰器
  2. 提取端点详细信息：
    • 从装饰器中获取HTTP方法（
      @router.post
      → POST）
    • 从装饰器参数中获取路径
    • 从函数文档字符串获取描述
    • 从函数签名中获取参数
    • 从
      response_model
      参数中获取响应模型
  3. 解析请求/响应模型：
    • 提取字段名称与类型
    • 生成JSON示例
    • 记录必填与可选字段
  4. 生成MDX文档文件：
    • 创建
      docs/api-reference/endpoint/{endpoint_name}.mdx
      文件
    • 包含描述、参数与示例
    • 添加至API参考文档索引
  5. 在
    .cursor/API_REFERENCE.md
    中添加新端点信息
  6. 验证文档格式与链接

Parsing FastAPI Routers

FastAPI路由解析

Implementation approach:
python
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
实现方式：
python
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
当添加新模块时：
  1. 检测新模块结构
  2. 更新架构文档
  3. 生成/更新Mermaid图
  4. 更新组件引用

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
  • .cursor/rules/documentation-standards.mdc
    - 文档规范
  • .cursor/rules/auto-documentation.mdc
    - 自动文档生成规则
  • .cursor/rules/backend-api-patterns.mdc
    - API设计模式

Subagents

子Agent

  • .cursor/agents/docs-generator.md
    - Documentation generation subagent
  • .cursor/agents/docs-generator.md
    - 文档生成子Agent

Commands

命令

  • /auto-docs
    - Trigger automatic documentation update
  • /update-api-docs
    - Update API reference documentation from FastAPI routers
  • /docs
    - Generate or update documentation
  • /auto-docs
    - 触发文档自动更新
  • /update-api-docs
    - 从FastAPI路由更新API参考文档
  • /docs
    - 生成或更新文档

Implementation Notes

实现说明

FastAPI Router Parsing

FastAPI路由解析

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
要自动生成API文档：
  1. 解析路由文件：使用AST解析Python文件并提取路由装饰器
  2. 提取元数据：从装饰器中获取方法、路径、参数与响应模型
  3. 解析文档字符串：从函数文档字符串中提取端点描述
  4. 生成示例：从Pydantic模型生成请求/响应示例
  5. 生成MDX文件：按照文档规范创建MDX文件
  6. 更新索引：将新端点添加至API参考文档索引

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
  • AST：Python的抽象语法树，用于解析Python代码
  • Pydantic：提取模型Schema以生成请求/响应示例
  • FastAPI：利用FastAPI的OpenAPI Schema生成能力
  • MDX：生成包含正确前置内容与格式的MDX文件

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
  • Git钩子：当路由文件变更时，在提交时触发
  • CI/CD：在CI流水线中运行，验证文档是否为最新版本
  • 手动触发：必要时使用
    /update-api-docs
    命令