文档生成Skill：自动生成API文档和注释

核心价值：文档生成Skill通过自动化技术从代码中提取结构信息并生成高质量文档，解决开发者最头疼的文档维护问题，确保代码与文档始终同步，大幅提升团队协作效率和项目可维护性。

一、文档生成Skill的设计

文档生成Skill的核心目标是从代码自动生成高质量文档，统一文档风格和格式，减少手动文档维护负担。在软件开发实践中，文档往往滞后于代码更新，导致团队成员和API使用者产生困惑。文档生成Skill通过深度集成到开发工作流中，在代码变更时同步更新文档，从根本上解决这一痛点。

一个优秀的文档生成Skill应当具备以下设计特性：首先是代码分析能力，能够解析源代码的抽象语法树（AST），提取函数签名、类结构、模块依赖等关键信息；其次是文档模板引擎，支持多种文档风格和输出格式的灵活切换；第三是增量更新机制，只对变更部分重新生成文档，避免全量覆盖带来的副作用；最后是可配置性，允许用户根据项目需求定制文档生成规则和内容粒度。

设计原则：文档生成Skill应遵循"约定优于配置"原则，内置一套合理的默认值，让开发者开箱即用，同时提供充分的定制接口以满足不同项目的特殊需求。

从工作流程来看，文档生成Skill通常分为三个阶段：分析阶段——扫描源代码文件，构建代码结构树；生成阶段——将结构信息填入文档模板，生成格式化文档内容；输出阶段——将生成的文档写入指定位置或直接插入到源代码中。这三个阶段可以串行执行，也可以独立调用，为开发者提供最大的灵活性。

在实际应用中，文档生成Skill可以集成到Git hooks中，在每次提交前自动更新相关文档；也可以作为CI/CD流水线的一个环节，在代码合并到主分支时触发文档的全面重新生成。这种自动化机制确保了文档始终反映代码的最新状态，彻底告别手动更新文档的繁琐工作。

设计维度	说明	推荐做法
代码分析	解析AST提取结构信息	使用语言特定的解析库（如Python的ast模块）
模板引擎	文档内容填充和格式化	采用Jinja2/Handlebars等成熟模板方案
增量更新	仅更新变更部分的文档	基于Git diff或文件哈希做变更检测
输出适配	支持多种文档格式	分层设计，核心逻辑与输出格式解耦

二、函数和类文档生成

函数和类文档是代码文档中最基础也最重要的组成部分。文档生成Skill通过读取源代码，分析函数签名和类型注解，自动生成符合规范的docstring，涵盖参数说明、返回值描述、异常类型和抛出条件，以及使用示例代码。

对于函数文档生成，Skill首先解析函数定义，提取函数名称、参数列表（包括默认值）、返回类型注解和文档字符串（如果已存在）。然后根据配置的文档风格（Google风格、NumPy风格或Sphinx风格），自动生成结构化的文档模板。对于参数，Skill不仅列出参数名称和类型，还会尝试从上下文推断参数的含义和约束条件。返回值部分的生成则结合返回类型注解和函数体中的return语句进行分析。

对于类文档生成，Skill扫描类的所有方法和属性，生成类的整体描述、初始化方法的参数说明、各个方法的独立文档以及类属性的类型描述。特别地，Skill能够识别常见的类设计模式（如单例模式、工厂模式、观察者模式等），并在文档中注明所使用的设计模式及其意图，这对于团队协作中的知识传递非常有价值。

# 文档生成Skill
- name: 生成文档
  command: doc
  prompt: |
    为以下代码生成文档：
    {{1}}
    选择合适的文档风格...
    包括：功能描述、参数说明、返回值、示例

下面是一个具体的生成示例。假设我们有如下的Python函数：

def calculate_statistics(data: list[float], normalize: bool = False) -> dict:
    if not data:
        raise ValueError("数据列表不能为空")
    n = len(data)
    mean = sum(data) / n
    variance = sum((x - mean) ** 2 for x in data) / n
    result = {"mean": mean, "std": variance ** 0.5, "count": n}
    if normalize:
        result["normalized"] = [(x - mean) / (variance ** 0.5) for x in data]
    return result

文档生成Skill会自动生成以下Google风格的docstring：

def calculate_statistics(data: list[float], normalize: bool = False) -> dict:
    """计算数据集的统计指标。

    Args:
        data: 输入数据列表，元素应为数值类型。
        normalize: 是否返回标准化后的数据，默认为False。

    Returns:
        dict: 包含以下键的字典：
            - mean: 算术平均值
            - std: 标准差
            - count: 数据点数量
            - normalized (可选): Z-score标准化后的数据列表

    Raises:
        ValueError: 如果data为空列表。

    Example:
        >>> calculate_statistics([1.0, 2.0, 3.0, 4.0, 5.0])
        {'mean': 3.0, 'std': 1.414, 'count': 5}
    """

技巧提示：为了实现高质量的文档生成，建议在代码中充分利用类型注解和默认值参数。类型注解越精确，生成的文档信息量越大。对于复杂的嵌套类型，可以使用typing模块中的泛型类型（如Dict[str, List[int]]）来提供更详细的类型信息。

在支持多种文档风格方面，Skill提供了灵活的配置选项。开发者可以在项目配置文件中指定所需的文档风格，Skill会根据配置自动调整生成内容的格式和结构。这种能力对于在不同文档标准之间切换的项目尤为重要，例如从Sphinx风格迁移到Google风格时，无需手动修改大量已有的文档字符串。

三、README文件创建

README文件是项目的门面，也是新用户了解项目的第一站。文档生成Skill通过分析项目结构和技术栈，自动生成完整的README.md文件，涵盖安装指南、使用说明、API概览、贡献指南等核心内容，并支持项目徽章和图表自动插入。

在生成README时，Skill会执行以下分析：扫描项目根目录和主要配置文件的项目结构分析，识别主要编程语言和框架的技术栈检测，分析依赖管理文件的依赖关系梳理，以及从已有代码中提取关键信息的核心功能归纳。

项目安装指南

根据项目类型自动生成pip、npm、cargo等包管理器的安装命令和系统依赖说明。

快速上手示例

提取测试用例或示例代码，生成可直接运行的入门示例，降低新用户使用门槛。

API参考概览

汇总公开API的列表和简要说明，方便用户快速了解项目提供的功能接口。

贡献指南模板

基于项目结构生成代码规范、提交流程和PR模板等贡献者文档框架。

一个典型的自动生成README结构如下：

# 项目名称

![License](https://img.shields.io/badge/license-MIT-blue)
![Python](https://img.shields.io/badge/python-3.9%2B-blue)
![Build](https://img.shields.io/github/actions/workflow/status/user/repo/ci.yml)

## 简介
简短的项目描述和目标说明。

## 安装
```bash
pip install your-package
```

## 快速开始
```python
from your_package import Client
client = Client()
result = client.process("example")
print(result)
```

## API
### Client
主要的客户端类，用于...

## 贡献
欢迎贡献！请阅读 CONTRIBUTING.md

## 许可证
MIT License

对于项目徽章的自动插入，Skill会根据项目配置文件自动检测：从pyproject.toml或package.json中提取版本号和许可证信息，从CI配置文件中提取构建状态，从测试覆盖率文件提取覆盖率数据，以及从仓库信息中提取GitHub Stars和Forks数量。这些徽章以Markdown图片链接的形式嵌入README中，提升项目的专业度和可信度。

四、API参考文档生成

API参考文档是面向API消费者的核心技术文档。文档生成Skill能够从代码注解中提取API定义，自动生成OpenAPI/Swagger规范，并支持多种输出格式，包括Markdown、HTML和JSON。

对于RESTful API项目，Skill解析Web框架（如FastAPI、Flask、Django REST Framework等）的路由定义和视图函数，提取每个端点的HTTP方法、URL路径、请求参数、请求体Schema和响应格式。结合Python类型注解和Pydantic模型定义，Skill能够生成完整的OpenAPI 3.0规范文档。

# FastAPI端点示例
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI(title="用户管理API", version="1.0.0")

class UserCreate(BaseModel):
    username: str
    email: str
    age: int | None = None

# Skill自动生成的OpenAPI片段：
# /users:
#   post:
#     summary: 创建新用户
#     requestBody:
#       required: true
#       content:
#         application/json:
#           schema:
#             $ref: '#/components/schemas/UserCreate'
#     responses:
#       '201':
#         description: 用户创建成功

生成的API文档不仅仅是一份静态的规范文件，Skill还可以将其渲染为交互式API文档（使用Swagger UI或Redoc），方便开发者在浏览器中直接测试API端点。对于非RESTful的API（如GraphQL、gRPC），Skill同样提供了对应的文档生成能力，支持从GraphQL Schema定义生成文档，以及从Protocol Buffer定义生成gRPC服务文档。

注意事项：自动生成的API文档虽然能覆盖大部分场景，但对于复杂的业务逻辑和异常情况，建议在自动生成的基础上进行人工补充说明。特别是涉及敏感数据处理的API端点，务必在文档中明确标注安全警告和权限要求。

在输出格式方面，Skill提供了灵活的适配器机制。Markdown格式适合嵌入到项目Wiki或GitHub Pages中，便于版本控制；HTML格式支持更丰富的样式和交互功能，适合部署到专门的文档站点；JSON/YAML格式（OpenAPI规范）则可以与其他API工具链集成，如API网关配置、客户端SDK生成和接口测试工具。

五、Changelog自动维护

Changelog是项目版本演进的完整记录，对于用户和开发者理解项目变化至关重要。文档生成Skill通过分析Git提交历史自动生成CHANGELOG.md，遵循语义化版本管理（SemVer）和Keep a Changelog标准格式。

Skill的Changelog生成流程包括：扫描Git提交历史，提取提交信息，并根据提交信息中的关键字（如"feat"、"fix"、"breaking"等）自动将变更分配到"新增"、"修复"、"变更"、"弃用"等分类中。对于遵循Conventional Commits规范的提交信息，Skill能够准确识别每次提交的类型和影响范围。

# Changelog

## [2.1.0] - 2026-05-08

### 新增
- 新增文档批量生成功能，支持一次处理多个源代码文件
- 新增OpenAPI 3.1规范支持，兼容最新的API文档标准
- CLI命令支持--config参数，允许指定自定义配置文件

### 修复
- 修复嵌套泛型类型在文档中的显示异常问题
- 修复中文注释在部分编码环境下的乱码问题
- 修复增量更新时模板缓存未正确刷新的问题

### 变更
- 升级依赖库版本，最低Python版本提升至3.10
- 默认文档风格从Sphinx切换为Google风格

## [2.0.0] - 2026-03-15

### 破坏性变更
- 配置文件格式全面重构，旧版本配置需迁移
- 移除对Python 3.8的支持

在版本管理方面，Skill读取项目配置文件中的当前版本号，结合Git标签（tag）信息和提交历史，自动建议下一个版本号。遵循语义化版本规范：破坏性API变更触发主版本号递增，新增功能保持向下兼容时触次版本号递增，Bug修复等微小变更触发补丁版本号递增。

最佳实践：为了让Changelog自动生成发挥最大价值，团队应当统一采用Conventional Commits规范编写提交信息（如feat: 添加用户导出功能、fix: 修复登录页样式问题）。这样Skill不仅能正确分类变更，还能在Changelog中生成更有意义的描述，避免出现"修复Bug"、"更新代码"等无信息量的条目。

六、多格式输出与集成

文档生成Skill支持多种文档输出格式，包括Markdown、reStructuredText（RST）和OpenAPI规范，能够适应不同类型项目的文档需求。

输出格式	适用场景	典型工具链
Markdown	GitHub/GitLab Wiki、静态站点生成器	MkDocs、Docusaurus、VitePress
reStructuredText	Python项目、Read the Docs	Sphinx、Read the Docs
OpenAPI (JSON/YAML)	RESTful API文档、API网关配置	Swagger UI、Redoc、Postman
HTML	独立部署的文档站点	JSDoc、pdoc、TypeDoc

对于Markdown格式，Skill利用模板引擎生成结构清晰的文档，支持代码高亮、表格、列表、引用等Markdown扩展语法。生成的Markdown文件可以直接在代码仓库中浏览，也可以导入到各种静态站点生成器中构建专业的文档网站。

对于reStructuredText格式，Skill特别针对Python生态进行了优化。生成的RST文件兼容Sphinx文档构建系统，支持自动生成模块索引、搜索功能和PDF输出。这对于需要发布到Read the Docs等文档托管平台的Python项目尤为有用。

七、内联代码注释规范化

内联代码注释是代码可读性的重要保障。文档生成Skill不仅生成外部文档，还能对源代码中的内联注释进行规范化和优化处理。

Skill分析现有的代码注释，检查注释格式是否统一、注释内容是否过时、以及是否存在应注释而未注释的关键代码段。在规范化过程中，Skill会：统一注释风格（如全部使用英文或中文）、修复错误的注释格式、补充缺失的关键逻辑注释、以及标记已过时的注释供人工确认。

注释规范推荐：代码注释应当解释"为什么做"（Why）而非"做了什么"（What）。好的注释说明设计决策的背景、算法的选择理由、以及边界条件处理的特殊考量。对于"做了什么"这类信息，应该通过清晰的代码结构和命名来表达，而不是依赖注释。

Skill还支持对TODO注释的管理。它会扫描代码中的TODO、FIXME、HACK等标记性注释，生成待办事项清单，按优先级和所在文件进行组织，帮助开发团队系统化地追踪技术债务。

八、核心要点总结

1. 自动化优先：文档生成Skill的核心价值在于将重复性的文档工作自动化，让开发者专注于代码质量本身。

2. 格式灵活：支持Google/NumPy/Sphinx多种文档风格，以及Markdown/RST/OpenAPI等输出格式，适配不同项目需求。

3. 深度集成：可嵌入Git hooks、CI/CD流水线、编辑器插件等工作流节点，实现文档的实时同步更新。

4. 智能分析：基于AST解析和类型注解，生成结构化的函数、类和方法文档，包含参数、返回值、异常等完整信息。

5. Changelog自动化：基于Conventional Commits和SemVer规范，从Git提交历史自动生成和维护变更日志。

6. 项目级文档：自动生成README、API参考和贡献指南，构建完整的项目文档体系。

7. 注释规范化：统一内联注释风格，补充缺失注释，管理TODO事项，提升代码可读性。

九、进一步思考

在实际项目中应用文档生成Skill时，有几个值得深入思考的方向：

文档质量与AI增强：当前基于AST的文档生成虽然准确，但生成的描述往往较为机械。结合大语言模型（如Claude）对代码语义的深层理解，可以生成更具可读性和洞察力的文档内容。例如，模型可以理解一个复杂算法的高层设计意图，并用通俗的语言解释给读者。

多语言项目支持：现代项目往往是多语言混合的（如Python后端+TypeScript前端）。文档生成Skill需要能够跨语言分析，建立统一的文档体系。例如，同时解析Python的FastAPI后端和TypeScript的React前端，生成一份涵盖全栈的API文档。

文档版本化：随着项目的演进，不同版本的文档需要对应不同的代码版本。文档生成Skill可以与Git标签和Release机制深度集成，确保用户查看的文档版本与所使用的代码版本精确匹配，避免因版本不一致导致的困惑。

定制化模板开发：虽然Skill内置了多种模板，但实际项目往往有独特的文档需求。支持用户开发自定义模板，并通过插件机制加载，能够极大地提升Skill的适用范围和团队接受度。