/generating-documentation

name: generating-documentation
description: Generate comprehensive technical documentation including API docs (OpenAPI/Swagger), code documentation (TypeDoc/Sphinx), documentation sites (Docusaurus/MkDocs), Architecture Decision Records (ADRs), and diagrams (Mermaid/PlantUML). Use when documenting APIs, libraries, systems architecture, or building developer-facing documentation sites.

Documentation Generation

Generate comprehensive technical documentation across multiple layers: API documentation, code documentation, documentation sites, architecture decisions, and system diagrams.

When to Use This Skill

Use this skill when:

• Documenting REST or GraphQL APIs with OpenAPI specifications
• Creating code documentation for libraries (TypeScript, Python, Go, Rust)
• Building documentation sites for projects or products
• Recording architectural decisions (ADRs) for system design choices
• Generating diagrams to visualize system architecture or data flows
• Setting up automated documentation pipelines in CI/CD

Documentation Layers Overview

Technical documentation operates at five distinct layers:

**Layer 1: API Documentation** - OpenAPI specs for REST/GraphQL APIs (Swagger UI, Redoc, Scalar) **Layer 2: Code Documentation** - Generated from code comments (TypeDoc, Sphinx, godoc, rustdoc) **Layer 3: Documentation Sites** - Comprehensive guides and tutorials (Docusaurus, MkDocs) **Layer 4: Architecture Decisions** - ADRs using MADR template format **Layer 5: Diagrams** - Visual architecture (Mermaid, PlantUML, D2)

See `references/api-documentation.md`, `references/code-documentation.md`, and `references/documentation-sites.md` for detailed guides.

Quick Decision Framework

Which Documentation Layer?

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)

Tool Selection Matrix

| Need | Primary Tool | Best For | |------|-------------|----------| | **Doc Site** | Docusaurus | Feature-rich React sites | | **Doc Site** | MkDocs Material | Simple Python docs | | **API Docs (Interactive)** | Swagger UI | Testing | | **API Docs (Read-Only)** | Redoc | Professional design | | **TypeScript** | TypeDoc | All TS projects | | **Python** | Sphinx | All Python projects | | **Go** | godoc | Built-in | | **Rust** | rustdoc | Built-in | | **Diagrams** | Mermaid | All-purpose |

API Documentation Quick Start

Create OpenAPI specification:

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: []

Render with Swagger UI, Redoc, or Scalar. See `references/api-documentation.md` for complete examples and `templates/openapi-template.yaml` for starter template.

Code Documentation Quick Start

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;
}

Generate docs:

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)

Generate docs:

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

See `references/code-documentation.md` for Go and Rust examples.

Documentation Site Quick Start

Docusaurus

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

Basic config:

// 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

Basic config:

# 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

See `references/documentation-sites.md` for versioning and deployment.

Architecture Decision Records

Use MADR template for recording decisions:

# Use Po