Build interactive tutorials using DocC
Developer Tools 进阶 20m

用 DocC 构建交互式教程

Build interactive tutorials using DocC

2021年6月10日

在 Apple 官方观看视频

一句话判断

DocC 的教程（Tutorial）功能让你的文档从 API 参考升级为引导式学习体验——Step by step 的交互式教程比任何 README 都管用。

这场 Session 讲了什么

Session 详细讲解了如何使用 DocC 创建交互式教程（Tutorial）。DocC 是 Apple 在 Xcode 13 中引入的文档编译器，除了生成 API 参考文档，还能生成步骤化的教程。教程由 .tutorial 文件定义，包含多个步骤（Step），每个步骤有介绍文字、代码片段和预览截图。

教程的结构是：Tutorial（一个完整的学习路径）-> Section（一个主题）-> Step（一个操作步骤）。每个 Step 可以包含代码片段（自动高亮差异）、Xcode 预览截图和解释文字。用户可以按步骤跟着操作，理解你的框架或库的使用方式。

Session 还介绍了教程的几种辅助组件：Article（独立的知识文章）、Tutorial Table of Contents（教程目录），以及如何在教程中引用 API 文档的链接。

值得深挖的点

代码差异高亮的自动处理

教程中的代码片段支持差异高亮（Diff Highlighting）——新增的代码行用绿色标记，删除的用红色标记，未改变的用灰色。你只需要在 .tutorial 文件中写每个步骤的完整代码，DocC 编译器会自动计算相邻步骤之间的差异。这大幅降低了维护教程的工作量——当你修改某个步骤的代码时，不需要手动更新前后的差异标记。

教程与 API 文档的双向链接

教程中的类型和方法可以自动链接到对应的 API 参考文档。用户在教程中看到 Sloth 类型，点击就能跳转到 Sloth 的完整 API 文档。反过来，API 文档页面也会显示”相关教程”的链接。这种双向链接让文档成为一个完整的知识网络，而不是孤立的页面。

代码片段

定义一个 Tutorial

// Tutorials/MyFramework/CreatingSloth.tutorial
@Tutorial {
    @Introduction(title: "创建你的第一个 Sloth") {
        本教程将指导你如何使用 MyFramework 创建和自定义 Sloth 对象。
    }
    
    @Section(title: "创建基本 Sloth") {
        @Steps {
            @Step {
                首先导入 MyFramework 框架。
                @Code(.swift, file: "CreatingSloth/Step1.swift")
            }
            @Step {
                使用 `Sloth` 的初始化方法创建一个实例。
                @Code(.swift, file: "CreatingSloth/Step2.swift")
            }
            @Step {
                给你的 Sloth 取一个名字并设置颜色。
                @Code(.swift, file: "CreatingSloth/Step3.swift")
            }
        }
    }
    
    @Section(title: "自定义 Sloth 的能力") {
        @Steps {
            @Step {
                使用 `addPower` 方法为 Sloth 添加特殊能力。
                @Code(.swift, file: "CreatingSloth/Step4.swift")
            }
        }
    }
}

教程中引用的代码文件

// CreatingSloth/Step1.swift
import MyFramework  // 新增：导入框架

// CreatingSloth/Step2.swift
import MyFramework

// 创建一个基本的 Sloth 实例
let sloth = Sloth()  // 新增：使用默认参数创建

定义 Tutorial Table of Contents

// Tutorials/MyFramework/MyFramework.tutorial
@Tutorials(name: "MyFramework 教程") {
    @Volume(name: "入门") {
        创建和自定义 Sloth 对象的基础知识。
        
        @Chapter(name: "基础") {
            @TutorialReference(tutorial: "doc:CreatingSloth")
        }
        
        @Chapter(name: "进阶") {
            @TutorialReference(tutorial: "doc:CustomizingPowers")
        }
    }
}

最佳实践

文档结构： 教程面向初次使用者，从零开始引导。Article 面向有经验的用户，深入讨论特定主题。API 参考面向查阅型需求。三者通过链接互相引用。先写 API 参考（自动生成），再补充教程和 Article。

教程设计： 每个步骤只做一件事。代码片段保持简短（10-20行）。每个 Section 的代码可以独立编译运行——用户不需要复制所有步骤的代码才能看到效果。在步骤之间使用预览截图让用户知道”运行后应该看到什么”。

还有什么值得关注

  • DocC 生成的文档可以在 Xcode 的 Documentation Viewer 中直接查看。
  • 教程支持 Swift 代码的语法高亮和自动格式化。
  • 可以在 CI 中用 xcodebuild docbuild 自动构建文档。
WWDC 2021