TypeDoc 高级主题 #

name: Documentation

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Build documentation
        run: npm run docs

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./docs

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

name: Documentation

on:
  release:
    types: [published]

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          registry-url: 'https://registry.npmjs.org'
      
      - run: npm ci
      
      - run: npm run docs
      
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs

stages:
  - build
  - deploy

build-docs:
  stage: build
  image: node:20
  script:
    - npm ci
    - npm run docs
  artifacts:
    paths:
      - docs/
    expire_in: 1 hour

pages:
  stage: deploy
  image: alpine:latest
  needs:
    - build-docs
  script:
    - mv docs public
  artifacts:
    paths:
      - public
  only:
    - main

version: 2.1

jobs:
  build-docs:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - restore_cache:
          keys:
            - v1-dependencies-{{ checksum "package-lock.json" }}
            - v1-dependencies-
      - run: npm ci
      - save_cache:
          paths:
            - node_modules
          key: v1-dependencies-{{ checksum "package-lock.json" }}
      - run: npm run docs
      - persist_to_workspace:
          root: .
          paths:
            - docs

  deploy-docs:
    docker:
      - image: cimg/node:20.0
    steps:
      - attach_workspace:
          at: .
      - run:
          name: Deploy to GitHub Pages
          command: |
            git config --global user.email "ci@example.com"
            git config --global user.name "CI"
            npx gh-pages -d docs

workflows:
  version: 2
  build-deploy:
    jobs:
      - build-docs
      - deploy-docs:
          requires:
            - build-docs
          filters:
            branches:
              only: main

monorepo/
├── packages/
│   ├── core/
│   │   ├── src/
│   │   ├── package.json
│   │   └── tsconfig.json
│   ├── utils/
│   │   ├── src/
│   │   ├── package.json
│   │   └── tsconfig.json
│   └── cli/
│       ├── src/
│       ├── package.json
│       └── tsconfig.json
├── typedoc.json
├── package.json
└── tsconfig.json

// typedoc.json
{
  "$schema": "https://typedoc.org/schema.json",
  "entryPointStrategy": "packages",
  "entryPoints": [
    "packages/core",
    "packages/utils",
    "packages/cli"
  ],
  "out": "docs",
  "name": "Monorepo Documentation",
  "includeVersion": true,
  "excludePrivate": true,
  "excludeInternal": true,
  "sort": ["source-order"],
  "visibilityFilters": {
    "protected": true,
    "private": false,
    "inherited": true,
    "external": false
  }
}

// packages/core/typedoc.json
{
  "extends": ["../../typedoc.base.json"],
  "entryPoints": ["src/index.ts"],
  "name": "@myorg/core",
  "readme": "./README.md"
}

// typedoc.base.json
{
  "excludePrivate": true,
  "excludeInternal": true,
  "sort": ["source-order"],
  "excludeExternals": true
}

# pnpm-workspace.yaml
packages:
  - 'packages/*'

// package.json
{
  "scripts": {
    "docs": "typedoc",
    "docs:core": "typedoc --entryPoints packages/core/src/index.ts --name @myorg/core",
    "docs:utils": "typedoc --entryPoints packages/utils/src/index.ts --name @myorg/utils"
  }
}

docs/
├── current/          # 最新版本
│   ├── index.html
│   └── ...
├── v2.0.0/          # 指定版本
│   ├── index.html
│   └── ...
├── v1.5.0/
│   ├── index.html
│   └── ...
└── index.html       # 版本选择页面

<!-- docs/index.html -->
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Documentation Versions</title>
  <style>
    body {
      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
      max-width: 800px;
      margin: 0 auto;
      padding: 40px 20px;
    }
    h1 { color: #333; }
    .version-list {
      list-style: none;
      padding: 0;
    }
    .version-list li {
      margin: 10px 0;
    }
    .version-list a {
      display: block;
      padding: 15px 20px;
      background: #f5f5f5;
      border-radius: 8px;
      text-decoration: none;
      color: #333;
    }
    .version-list a:hover {
      background: #e5e5e5;
    }
    .version-list .current {
      background: #4f6bed;
      color: white;
    }
  </style>
</head>
<body>
  <h1>Documentation Versions</h1>
  <ul class="version-list">
    <li>
      <a href="./current/index.html" class="current">
        <strong>Current (v2.1.0)</strong> - Latest version
      </a>
    </li>
    <li>
      <a href="./v2.0.0/index.html">
        v2.0.0 - Major release
      </a>
    </li>
    <li>
      <a href="./v1.5.0/index.html">
        v1.5.0 - Legacy version
      </a>
    </li>
  </ul>
</body>
</html>

// scripts/build-versioned-docs.js
const { execSync } = require('child_process');
const fs = require('fs');
const path = require('path');

const version = require('../package.json').version;
const docsDir = path.join(__dirname, '..', 'docs');
const versionDir = path.join(docsDir, `v${version}`);
const currentDir = path.join(docsDir, 'current');

console.log(`Building documentation for version ${version}`);

// 生成文档
execSync('npm run docs', { stdio: 'inherit' });

// 创建版本目录
if (!fs.existsSync(versionDir)) {
  fs.mkdirSync(versionDir, { recursive: true });
}

// 复制文档到版本目录
fs.cpSync(path.join(docsDir, 'api'), versionDir, { recursive: true });

// 更新 current 链接
if (fs.existsSync(currentDir)) {
  fs.rmSync(currentDir, { recursive: true });
}
fs.cpSync(versionDir, currentDir, { recursive: true });

console.log(`Documentation built at:`);
console.log(`  - ${versionDir}`);
console.log(`  - ${currentDir}`);

name: Versioned Docs

on:
  release:
    types: [published]

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - run: npm ci
      
      - name: Build docs
        run: npm run docs
      
      - name: Setup versioned docs
        run: |
          VERSION=${GITHUB_REF#refs/tags/v}
          mkdir -p docs-versions
          cp -r docs docs-versions/v$VERSION
          cp -r docs docs-versions/current
      
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs-versions
          keep_files: true

{
  "entryPoints": ["src/index.ts"],
  "exclude": [
    "**/*.test.ts",
    "**/*.spec.ts",
    "**/node_modules/**"
  ]
}

{
  "exclude": [
    "node_modules",
    "dist",
    "**/*.test.ts",
    "**/*.spec.ts",
    "**/internal/**",
    "**/__tests__/**"
  ],
  "excludePrivate": true,
  "excludeInternal": true,
  "excludeExternals": true
}

{
  "tsconfig": "./tsconfig.json",
  "compilerOptions": {
    "incremental": true
  }
}

# 增加 Node.js 内存
export NODE_OPTIONS="--max-old-space-size=4096"
npx typedoc

# GitHub Actions 缓存
- name: Cache dependencies
  uses: actions/cache@v3
  with:
    path: |
      node_modules
      .typedoc-cache
    key: ${{ runner.os }}-typedoc-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-typedoc-

DEBUG=typedoc npx typedoc

{
  "json": "docs/api.json",
  "pretty": true
}

// 使用 @resolve 查看类型解析结果
/**
 * @resolve
 */
function complexFunction<T extends Record<string, any>>(
  data: T
): Promise<{ [K in keyof T]: string }> {
  // ...
}

// 问题：类型显示为 any
// 解决：确保 tsconfig.json 正确配置

// 问题：注释不显示
// 解决：检查注释格式是否正确
/**
 * 正确的注释格式
 * @param name - 参数说明
 */

// 问题：链接不工作
// 解决：使用正确的链接语法
/**
 * @see {@link ClassName}
 * @see {@link ClassName.methodName}
 * @see {@link https://example.com | 外部链接}
 */

/**
 * 函数简短描述
 * 
 * 详细描述，可以包含更多说明。
 * 支持多行文本和 Markdown 格式。
 * 
 * @typeParam T - 泛型参数说明
 * @param param1 - 参数1说明
 * @param param2 - 参数2说明
 * @returns 返回值说明
 * @throws {ErrorType} 异常说明
 * 
 * @example
 * ```typescript
 * // 使用示例
 * const result = functionName(arg1, arg2);
 * ```
 * 
 * @see {@link relatedFunction} 相关函数
 * @since 1.0.0
 */

project/
├── src/
│   ├── index.ts           # 主入口，导出所有公开 API
│   ├── public/            # 公开 API
│   ├── internal/          # 内部实现（排除文档）
│   └── __tests__/         # 测试文件（排除文档）
├── docs/
│   └── assets/            # 文档资源
├── typedoc.json           # TypeDoc 配置
├── tsconfig.json          # TypeScript 配置
└── package.json

{
  "scripts": {
    "docs": "typedoc",
    "docs:watch": "typedoc --watch",
    "docs:serve": "typedoc --serve",
    "docs:json": "typedoc --json docs/api.json",
    "docs:clean": "rm -rf docs",
    "docs:deploy": "npm run docs && gh-pages -d docs"
  }
}

✅ 环境准备
   ├── Node.js 版本一致
   ├── 依赖安装正确
   └── TypeScript 版本匹配

✅ 构建流程
   ├── 类型检查通过
   ├── 测试全部通过
   └── 文档生成成功

✅ 部署流程
   ├── 输出目录正确
   ├── 静态资源完整
   └── 链接全部有效

✅ 版本管理
   ├── 版本号正确
   ├── 变更日志更新
   └── 文档同步发布

入门阶段
├── TypeDoc 简介 ✅
├── 安装与配置 ✅
└── 基本使用 ✅

进阶阶段
├── 配置详解 ✅
├── 注解标签 ✅
└── 主题定制 ✅

高级阶段
├── 插件扩展 ✅
├── CI/CD 集成 ✅
└── 性能优化 ✅

实战阶段
├── 开源库文档
├── 组件库文档
└── 企业级文档系统