⚡

文档生成Skill generating-documentation

这个技能用于生成全面的技术文档，覆盖API文档、代码文档、文档站点、架构决策记录和图表。它帮助开发者和团队文档化系统架构、API接口和代码库，提高文档质量和可维护性，支持自动化文档生成和CI/CD管道。关键词：技术文档、API文档、代码文档、文档站点、ADRs、图表、自动化文档生成、CI/CD管道。

DevOps 0 次安装 0 次浏览 更新于 3/23/2026

名称: 生成文档 描述: 生成全面的技术文档，包括API文档（OpenAPI/Swagger）、代码文档（TypeDoc/Sphinx）、文档站点（Docusaurus/MkDocs）、架构决策记录（ADRs）和图表（Mermaid/PlantUML）。适用于文档化API、库、系统架构或构建面向开发者的文档站点。

文档生成

生成全面的技术文档，覆盖多个层面：API文档、代码文档、文档站点、架构决策和系统图表。

何时使用此技能

在以下情况下使用此技能：

  • 使用OpenAPI规范文档化REST或GraphQL API
  • 为库（TypeScript、Python、Go、Rust）创建代码文档
  • 为项目或产品构建文档站点
  • 记录系统设计决策的架构决策记录（ADRs）
  • 生成图表以可视化系统架构或数据流
  • 在CI/CD中设置自动化文档管道

文档层面概述

技术文档在五个不同层面运作：

层面1: API文档 - REST/GraphQL API的OpenAPI规范（Swagger UI、Redoc、Scalar） 层面2: 代码文档 - 从代码注释生成（TypeDoc、Sphinx、godoc、rustdoc） 层面3: 文档站点 - 全面的指南和教程（Docusaurus、MkDocs） 层面4: 架构决策 - 使用MADR模板格式的ADRs 层面5: 图表 - 可视化架构（Mermaid、PlantUML、D2）

详情请参阅 references/api-documentation.md、references/code-documentation.md 和 references/documentation-sites.md。

快速决策框架

选择哪个文档层面？

为外部消费者提供API？
  → 层面1: API文档（OpenAPI + Swagger UI/Redoc）

为维护者提供代码？
  → 层面2: 代码文档（TypeDoc/Sphinx/godoc/rustdoc）

需要全面指南？
  → 层面3: 文档站点（Docusaurus/MkDocs）

有架构决策？
  → 层面4: ADR（MADR模板）

需要可视化系统设计？
  → 层面5: 图表（Mermaid/PlantUML/D2）

工具选择矩阵

需求 主要工具 最适用于
文档站点 Docusaurus 功能丰富的React站点
文档站点 MkDocs Material 简单的Python文档
API文档（交互式） Swagger UI 测试
API文档（只读） Redoc 专业设计
TypeScript TypeDoc 所有TS项目
Python Sphinx 所有Python项目
Go godoc 内置
Rust rustdoc 内置
图表 Mermaid 多功能

API文档快速入门

创建OpenAPI规范：

openapi: 3.1.0
info:
  title: 用户API
  version: 1.0.0

servers:
  - url: https://api.example.com/v1

paths:
  /users/{userId}:
    get:
      summary: 获取用户
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

components:
  schemas:
    User:
      type: object
      required: [id, email, name]
      properties:
        id:
          type: string
        email:
          type: string
          format: email
        name:
          type: string

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - bearerAuth: []

使用Swagger UI、Redoc或Scalar渲染。完整示例请参阅 references/api-documentation.md，入门模板请参阅 templates/openapi-template.yaml。

代码文档快速入门

TypeScript

/**
 * 计算两个数字的和。
 *
 * @param a - 第一个数字
 * @param b - 第二个数字
 * @returns a和b的和
 *
 * @example
 * ```typescript
 * const result = add(2, 3);
 * console.log(result); // 5
 * ```
 */
export function add(a: number, b: number): number {
  return a + b;
}

生成文档：

npm install -D typedoc
npx typedoc --entryPoints src/index.ts --out docs

Python

def calculate_total(items: list[dict], tax_rate: float = 0.0) -> float:
    """计算包括税的总价。

    Args:
        items: 包含'price'和'quantity'键的项目列表。
        tax_rate: 税率作为小数（例如，0.1表示10%）。

    Returns:
        包括税的总价。

    Example:
        >>> items = [{'price': 10, 'quantity': 2}]
        >>> calculate_total(items, tax_rate=0.1)
        22.0
    """
    subtotal = sum(item['price'] * item['quantity'] for item in items)
    return subtotal * (1 + tax_rate)

生成文档：

pip install sphinx sphinx-rtd-theme
sphinx-quickstart docs
cd docs && make html

Go和Rust示例请参阅 references/code-documentation.md。

文档站点快速入门

Docusaurus

npx create-docusaurus@latest my-website classic
cd my-website
npm start

基本配置：

// docusaurus.config.js
module.exports = {
  title: '我的项目',
  url: 'https://docs.example.com',
  themeConfig: {
    navbar: {
      items: [
        {type: 'doc', docId: 'intro', label: '文档'},
      ],
    },
  },
  presets: [
    ['@docusaurus/preset-classic', {
      docs: {
        sidebarPath: require.resolve('./sidebars.js'),
      },
    }],
  ],
};

MkDocs

pip install mkdocs mkdocs-material
mkdocs new my-project
mkdocs serve

基本配置：

# mkdocs.yml
site_name: 我的项目
theme:
  name: material
  features:
    - navigation.tabs
    - search.suggest

plugins:
  - search

nav:
  - 主页: index.md
  - 入门指南: getting-started.md

版本化和部署请参阅 references/documentation-sites.md。

架构决策记录

使用MADR模板记录决策：

# 使用PostgreSQL作为主数据库

* 状态: 已接受
* 决策者: 工程团队、CTO
* 日期: 2025-01-15

## 背景和问题陈述

应用需要关系型数据库，支持复杂查询、ACID事务、JSON支持和全文搜索。

## 决策驱动因素

* 数据完整性（ACID合规）
* 性能（每秒10K+查询）
* 成本（优先开源）
* 功能（JSONB、全文搜索）

## 考虑选项

* PostgreSQL
* MySQL
* Amazon Aurora

## 决策结果

选择"PostgreSQL"，因其功能和成本的最佳平衡。

### 正面后果

* 开源无许可成本
* 高级功能（JSONB、全文搜索）
* 强ACID合规

### 负面后果

* 自托管需要DevOps投资
* 水平扩展需要更改

完整模板从 templates/adr-template.md 复制。工作流和完整示例请参阅 references/adr-guide.md 和 examples/adr/0001-database-selection.md。

图表快速入门

使用Mermaid创建图表：

```mermaid
sequenceDiagram
    User->>Frontend: 点击“登录”
    Frontend->>API: POST /auth/login
    API->>Database: 验证凭证
    Database-->>API: 用户找到
    API-->>Frontend: JWT令牌
    Frontend->>User: 重定向到仪表板
```

Mermaid在GitHub、Docusaurus和MkDocs中渲染。PlantUML和D2示例请参阅 references/diagram-generation.md。

常见模式

设计优先 vs 代码优先 API

设计优先:

  1. 编写OpenAPI规范
  2. 与利益相关者评审
  3. 生成服务器存根
  4. 实现处理程序

优点: 实现前有合约，并行开发 缺点: 规范编写可能冗长

代码优先:

  1. 使用装饰器实现API
  2. 从代码生成OpenAPI
  3. 发布文档

优点: 开发更快，规范匹配代码 缺点: 文档滞后

推荐: 新API用设计优先，现有API用代码优先。

在站点中嵌入API文档

Docusaurus集成：

// docusaurus.config.js
plugins: [
  ['docusaurus-plugin-openapi-docs', {
    config: {
      api: {
        specPath: 'openapi/api.yaml',
        outputDir: 'docs/api',
      },
    },
  }],
],
themes: ['docusaurus-theme-openapi-docs'],

MkDocs集成请参阅 references/api-documentation.md。

CI/CD自动化

# .github/workflows/docs.yml
name: 文档

on:
  push:
    branches: [main]

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4

      - name: 生成API文档
        run: npm run docs:api

      - name: 生成代码文档
        run: npm run docs:code

      - name: 构建站点
        run: npm run docs:build

      - name: 部署到GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./build

验证和版本化请参阅 references/ci-cd-integration.md。

何时编写ADR

编写ADR用于:

✅ 技术选择（数据库、框架、云） ✅ 架构模式（微服务、事件驱动） ✅ 有权衡的决策（优缺点） ✅ 需要团队对齐

不要编写ADR用于:

❌ 琐碎决策（命名、格式化） ❌ 容易逆转（配置调整） ❌ 实现细节（在代码中记录）

工作流和示例请参阅 references/adr-guide.md。

参考文档

详细指南：

  • references/api-documentation.md - OpenAPI、Swagger UI、Redoc、Scalar、设计优先 vs 代码优先
  • references/code-documentation.md - TypeDoc、Sphinx、godoc、rustdoc示例
  • references/documentation-sites.md - Docusaurus和MkDocs设置、版本化、部署
  • references/adr-guide.md - MADR模板、工作流、何时编写ADRs
  • references/diagram-generation.md - Mermaid、PlantUML、D2语法和集成
  • references/ci-cd-integration.md - 自动化、验证、部署策略

模板

  • templates/adr-template.md - 架构决策记录的MADR模板
  • templates/openapi-template.yaml - OpenAPI 3.1规范入门

示例

  • examples/openapi/ - 完整OpenAPI规范
  • examples/typescript/ - TypeDoc配置和TSDoc示例
  • examples/python/ - Sphinx配置和文档字符串示例
  • examples/adr/ - 真实世界架构决策记录
  • examples/diagrams/ - Mermaid、PlantUML、D2示例

工具推荐

基于研究（2025年12月）：

文档站点:

  • Docusaurus - 基于React，功能丰富（版本化、i18n、搜索）
  • MkDocs Material - 基于Python，简单美观

API文档:

  • Swagger UI - 交互式测试
  • Redoc - 美观只读
  • Scalar - 现代2025设计

代码文档:

  • TypeScript: TypeDoc
  • Python: Sphinx
  • Go: godoc（内置）
  • Rust: rustdoc（内置）

图表:

  • Mermaid - 最流行，GitHub集成
  • PlantUML - UML标准
  • D2 - 现代声明式

与其他技能集成

  • api-patterns - API实现和文档
  • building-ci-pipelines - 自动化文档生成
  • testing-strategies - 文档测试模式
  • sdk-design - 生成SDK文档

最佳实践

  1. 文档即代码 - 将文档保存在版本控制中
  2. 单一来源 - 从代码/规范生成
  3. 自动化 - 在CI/CD管道中生成
  4. 示例 - 包括可运行代码示例
  5. 验证 - 检查Markdown，验证规范
  6. 版本化 - 文档随发布版本化
  7. 一致性 - 使用一致术语
  8. 维护 - 代码更改时更新文档

常见陷阱

文档漂移 - 文档过时 → 自动化生成，在CI/CD中验证

过度文档化 - 记录明显行为 → 关注“为什么”而不是“什么”

碎片化文档 - 信息分散 → 单一站点，清晰导航

无示例 - 只有理论没有实践 → 包括可运行示例