generating-documentation

ドキュメント生成

API ドキュメント、コードドキュメント、ドキュメントサイト、アーキテクチャ上の決定、システム図など、複数の層にわたる包括的な技術ドキュメントを生成します。

このスキルを使用する場面

次の場合にこのスキルを使用します。

• OpenAPI 仕様を使用して REST API または GraphQL API をドキュメント化する場合
• ライブラリ（TypeScript、Python、Go、Rust）のコードドキュメントを作成する場合
• プロジェクトや製品のドキュメントサイトを構築する場合
• システム設計上の選択をアーキテクチャ決定記録（ADR）に残す場合
• システムアーキテクチャやデータフローを可視化する図を生成する場合
• CI/CD でドキュメント生成パイプラインを設定する場合

ドキュメントの各層の概要

技術ドキュメントは、次の 5 つの異なる層で構成されます。

レイヤー 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 の設定と docstring の例
• 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. Docs-as-Code - ドキュメントをバージョン管理下に置く
2. 信頼できる唯一の情報源 - コード／仕様から生成する
3. 自動化 - CI/CD パイプラインで生成する
4. 例 - 動作するコード例を含める
5. 検証 - Markdown を lint し、仕様を検証する
6. バージョン管理 - リリースに合わせてドキュメントをバージョン管理する
7. 一貫性 - 用語を統一する
8. 保守 - コードの変更時に更新する

よくある落とし穴

ドキュメントの陳腐化 - ドキュメントが古くなる → 生成を自動化し、CI/CD で検証する

過剰なドキュメント化 - 明白な動作まで説明する → 「何を」ではなく「なぜ」に焦点を当てる

ドキュメントの分散 - 情報があちこちに散らばる → 明確なナビゲーションを備えた単一のサイトにまとめる

例がない - 実践を伴わない理論 → 実行可能な例を含める