generating-documentation

文档生成

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

何时使用此技能

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

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

文档层概览

技术文档分为五个不同层面：

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

详细指南请参见 references/api-documentation.md、references/code-documentation.md 和 references/documentation-sites.md。

快速决策框架

选择哪个文档层？

API for external consumers?
  → Layer 1: API Documentation (OpenAPI + Swagger UI/Redoc)

Code for maintainers?
  → Layer 2: Code Documentation (TypeDoc/Sphinx/godoc/rustdoc)

Comprehensive guides?
  → Layer 3: Documentation Site (Docusaurus/MkDocs)

Architectural decision?
  → Layer 4: ADR (MADR template)

Visual system design?
  → Layer 5: Diagrams (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: User API
  version: 1.0.0

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

paths:
  /users/{userId}:
    get:
      summary: Get a user
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
          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

/**
 * Calculate the sum of two numbers.
 *
 * @param a - The first number
 * @param b - The second number
 * @returns The sum of a and 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:
    """Calculate the total price including tax.

    Args:
        items: List of items with 'price' and 'quantity' keys.
        tax_rate: Tax rate as decimal (e.g., 0.1 for 10%).

    Returns:
        Total price including tax.

    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: 'My Project',
  url: 'https://docs.example.com',
  themeConfig: {
    navbar: {
      items: [
        {type: 'doc', docId: 'intro', label: 'Docs'},
      ],
    },
  },
  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: My Project
theme:
  name: material
  features:
    - navigation.tabs
    - search.suggest

plugins:
  - search

nav:
  - Home: index.md
  - Getting Started: getting-started.md

版本管理和部署请参见 references/documentation-sites.md。

架构决策记录

使用 MADR 模板记录决策：

# Use PostgreSQL for Primary Database

* Status: accepted
* Deciders: Engineering Team, CTO
* Date: 2025-01-15

## Context and Problem Statement

Application requires relational database with complex queries,
ACID transactions, JSON support, and full-text search.

## Decision Drivers

* Data integrity (ACID compliance)
* Performance (10K+ queries/second)
* Cost (open-source preferred)
* Features (JSONB, full-text search)

## Considered Options

* PostgreSQL
* MySQL
* Amazon Aurora

## Decision Outcome

Chosen "PostgreSQL" for best balance of features and cost.

### Positive Consequences

* Open-source with no licensing costs
* Advanced features (JSONB, full-text search)
* Strong ACID compliance

### Negative Consequences

* Self-hosting requires DevOps investment
* Horizontal scaling requires changes

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

图表快速入门

使用 Mermaid 创建图表：

```mermaid
sequenceDiagram
    User->>Frontend: Click "Login"
    Frontend->>API: POST /auth/login
    API->>Database: Verify credentials
    Database-->>API: User found
    API-->>Frontend: JWT token
    Frontend->>User: Redirect to dashboard
```

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

常见模式

设计优先型与代码优先型 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: Documentation

on:
  push:
    branches: [main]

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

      - name: Generate API docs
        run: npm run docs:api

      - name: Generate code docs
        run: npm run docs:code

      - name: Build site
        run: npm run docs:build

      - name: Deploy to 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、设计优先与代码优先
• references/code-documentation.md - TypeDoc、Sphinx、godoc、rustdoc 及示例
• references/documentation-sites.md - Docusaurus 和 MkDocs 的配置、版本管理与部署
• references/adr-guide.md - MADR 模板、工作流、何时编写 ADR
• 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，功能丰富（版本管理、国际化、搜索）
• 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 中验证

过度记录 - 记录显而易见的行为 → 关注“为什么”，而不是“是什么”

文档零散 - 信息分散 → 使用导航清晰的单一站点

没有示例 - 只有理论，没有实践 → 包含可运行的示例