Host and automate your DocC documentation
Developer Tools 进阶 20m

托管和自动化你的 DocC 文档

Host and automate your DocC documentation

2021年6月10日

在 Apple 官方观看视频

一句话判断

DocC 文档可以导出为静态网站——这意味着你可以把它托管在任何地方（GitHub Pages、Netlify、甚至自己的服务器），还支持搜索和导航。

这场 Session 讲了什么

Session 介绍了如何将 DocC 生成的文档导出为可托管的静态网站，以及如何在 CI 中自动化文档构建和发布流程。

DocC 编译器可以生成两种输出：Xcode 内部的文档包（.doccarchive）和静态网站（一组 HTML/CSS/JS 文件）。静态网站版本支持完整的搜索、导航、教程交互，不需要任何服务器端逻辑——纯静态文件就能运行。

Session 详细讲解了导出流程：用 xcodebuild docbuild 构建文档，用 docc process-archive 转换为静态网站，然后部署到 GitHub Pages 或其他静态托管服务。

还介绍了如何在 GitHub Actions 等 CI 中自动化这个过程——每次代码合并到主分支时自动构建文档并发布，保证文档始终和代码同步。

值得深挖的点

静态网站的搜索实现

DocC 的静态网站搜索不需要后端服务器。编译时 DocC 会生成一个搜索索引 JSON 文件，客户端的 JavaScript 代码加载这个索引并在浏览器中执行搜索。这意味着搜索速度非常快（本地索引 + 内存搜索），但索引大小随文档规模增长——大型框架的搜索索引可能有几 MB。如果文档很大，需要考虑按模块拆分文档。

文档版本的策略

对于持续迭代的框架，文档版本管理是一个实际问题。Session 建议用 URL 路径区分版本（如 /docs/1.2/ 和 /docs/main/），CI 中同时发布稳定版和开发版的文档。主分支构建发布到 /docs/main/，tag 构建发布到 /docs/{version}/。用重定向让 /docs/latest/ 指向最新的稳定版。

代码片段

构建 DocC 文档并导出静态网站

// 1. 构建文档
// xcodebuild docbuild \
//   -scheme MyFramework \
//   -destination 'platform=iOS Simulator,name=iPhone 13' \
//   -derivedDataPath build/

// 2. 找到生成的 .doccarchive
// find build -name "*.doccarchive"

// 3. 转换为静态网站
// $(xcrun --find docc) process-archive \
//   transform-for-static-hosting build/Build/Products/Debug-iphonesimulator/MyFramework.doccarchive \
//   --output-path docs/output \
//   --hosting-base-path "/MyFramework"

// 4. docs/output 目录包含可直接托管的静态文件

GitHub Actions 自动化部署

# .github/workflows/docs.yml
name: Publish Docs
on:
  push:
    branches: [main]
    
jobs:
  publish:
    runs-on: macos-12
    steps:
      - uses: actions/checkout@v3
      
      - name: Build documentation
        run: |
          xcodebuild docbuild \
            -scheme MyFramework \
            -derivedDataPath build
          
          $(xcrun --find docc) process-archive \
            transform-for-static-hosting \
            $(find build -name "*.doccarchive" | head -1) \
            --output-path docs/output \
            --hosting-base-path "/MyFramework"
      
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs/output

本地预览文档

// 在本地启动一个预览服务器
// cd docs/output
// python3 -m http.server 8000

// 或用 DocC 内置的预览功能：
// $(xcrun --find docc) preview \
//   build/Build/Products/Debug-iphonesimulator/MyFramework.doccarchive

// 浏览器打开 http://localhost:8000 即可预览

最佳实践

CI 集成： 把文档构建纳入 CI 流程。每次 PR 都检查文档是否能成功构建（docbuild），每个合并到主分支的 commit 自动发布新文档。文档构建失败应该阻塞合并——如果你的 API 注释有语法错误，文档就不会生成。

托管选择： GitHub Pages 适合开源项目（免费、和 GitHub 集成好）。Netlify 或 Vercel 适合需要自定义域名和 CDN 的项目。内部项目可以部署到公司的静态文件服务器。

还有什么值得关注

  • DocC 静态网站支持深色模式，自动跟随系统设置。
  • 文档中的代码块支持一键复制。
  • --hosting-base-path 参数用于设置子路径部署（如 GitHub Pages 的项目站点）。
WWDC 2021