Create rich documentation with Swift-DocC

Highlight

Xcode 15 为 Swift-DocC 带来了 Documentation Preview 实时预览编辑器、扩展符号文档化、网格布局、Tab 导航器、视频嵌入、自定义主题等能力，让开发者可以创建与产品网站风格一致的丰富文档。

核心内容

扩展符号文档化

Swift 的 extension 是强大的语言特性，但以前 DocC 不会为扩展外部类型的符号生成文档页面。这意味着你给 SwiftUI 的 Image 加了一个便利构造方法，文档里却找不到它。

（06:21）Xcode 15 解决了这个问题。现在扩展符号会出现在文档的 “Extended Modules” 区域，与项目其他符号并列展示。这个功能完全由社区贡献驱动，涉及 Swift-DocC 和 Swift 编译器的协调改动。

Documentation Preview 编辑器

（08:05）这是 Xcode 15 最亮眼的文档功能。在源码编辑器中，通过 Editor > Assistant > Documentation Preview 打开实时预览面板。每输入一个字符，预览都会即时更新，显示文档最终渲染效果。

预览面板会在你切换 Swift 源文件、Objective-C 头文件和 Markdown 文档文件时保持活跃，让你在整个项目中都能边写边看。

丰富的页面布局指令

（16:18）DocC 新增了一系列 Markdown 指令，让文档排版更灵活：

@Row + @Column：网格布局，图文并排
@TabNavigator + @Tab：Tab 切换器，节省纵向空间
@Video：嵌入视频，增强互动性
@Links：以卡片网格形式展示相关链接
@CallToAction：为页面添加醒目的行动按钮
@PageKind(sampleCode)：将页面标记为示例代码类型
@PageImage / @PageColor：自定义页面图标和主题色

自定义主题

（25:22）通过在 Documentation Catalog 中放置 theme-settings.json，可以为网页版文档定制颜色和字体，让文档网站与产品网站保持视觉一致。自定义主题只影响网页部署，Xcode 内的文档仍使用 Xcode 主题。

（31:02）所有用 Xcode 15 构建的 Swift-DocC 网站都支持 Quick Navigation。按 Shift-Command-O 打开，输入页面名称即可快速跳转，类似 Xcode 的 Open Quickly 功能。

详细内容

为扩展编写文档注释

（08:52）为 SwiftUI 的 Image 扩展添加文档：

import SwiftUI

/// An extension that facilitates the display of sloths in user interfaces.
public extension Image {
    /// Create an image from the given sloth.
    ///
    /// Use this initializer to display an image representation of a
    /// given sloth.
    ///
    /// ```swift
    /// let iceSloth = Sloth(name: "Super Sloth", color: .blue, power: .ice)
    ///
    /// var body: some View {
    ///     Image(iceSloth)
    ///         .resizable()
    ///         .aspectRatio(contentMode: .fit)
    ///     Text(iceSloth.name)
    /// }
    /// ```
    ///
    /// ![A screenshot of an ice sloth, with the text Super Sloth underneath.](iceSloth)
    ///
    /// This initializer is useful for displaying static sloth images.
    /// To create an interactive view containing a sloth, use ``SlothView``.
    init(_ sloth: Sloth) {
        self.init("\(sloth.power)-sloth")
    }
}

关键点：

三斜杠 /// 开头表示文档注释
第一行是摘要，出现在符号列表中
后续段落构成 Discussion 部分
用 Markdown 代码块展示使用示例
![alt](filename) 引用 Documentation Catalog 中的图片
`SlothView` 创建指向其他符号的链接
DocC 会自动匹配图片的浅色/深色模式版本

网格布局

（16:31）用 @Row 和 @Column 创建图文并排布局：

@Row {
    @Column(size: 2) {
        First, you customize your sloth by picking its 
        ``Sloth/power-swift.property``. The power of your sloth influences
        its abilities and how well they cope in their environment. The app
        displays a picker view that showcases the available powers and
        previews your sloth for the selected power.
    }
    
    @Column {
        ![A screenshot of the power picker user interface with four powers displayed – ice, fire, wind, and lightning](slothy-powerPicker)
    }
}

@Row {
    @Column {
        ![A screenshot of the sloth status user interface that indicates the the amount of sleep, fun, and exercise a given sloth is in need of.](slothy-status)
    }
    
    @Column(size: 2) {
        Once you've customized your sloth, it's ready to ready to thrive.
        You'll find that sloths will happily munch on a leaf, but may not be as 
        receptive to working out. Use the activity picker to send some
        encouragement.
    }
}

关键点：

@Row 定义一行，内部包含多个 @Column
@Column(size: 2) 让该列占据 2 份宽度（默认 1 份）
网格总宽度为 4 列，所以 size: 2 占一半
图文顺序可以灵活调整（左文右图或左图右文）

Tab 导航器

（18:16）用 @TabNavigator 折叠多语言截图：

@TabNavigator {
    @Tab("English") {
        ![Two screenshots showing the Slothy app rendering with English language content.](slothy-localization_eng)
    }
    
    @Tab("Chinese") {
        ![Two screenshots showing the Slothy app rendering with Chinese language content.](slothy-localization_zh)
    }
    
    @Tab("Spanish") {
        ![Two screenshots showing the Slothy app rendering with Spanish language content.](slothy-localization_es)
    }
}

关键点：

@TabNavigator 包裹所有 Tab
每个 @Tab("标题") 定义一个标签页
适合展示同一内容的不同变体（语言、主题、平台）
大幅节省纵向空间，避免长页面滚动

嵌入视频

（19:07）

@Video(poster: "slothy-hero-poster", source: "slothy-hero", alt: "An animated video showing two screens in the Slothy app.")

关键点：

poster 是视频封面图，播放前显示
source 是视频文件
alt 提供无障碍描述
视频文件放在 Documentation Catalog 中

页面元数据

（19:50）用 @Metadata 添加页面级配置：

@Metadata {
    @CallToAction(purpose: link, url: "https://example.com/slothy-repository")
    @PageKind(sampleCode)
    @PageImage(purpose: card, source: "slothy-card", alt: "Two screenshots showing the Slothy app.")
    @PageImage(purpose: icon, source: "slothCreator-icon", alt: "A technology icon representing the SlothCreator framework.")
    @PageColor(green)
}

关键点：

@CallToAction 在页面顶部添加行动按钮，purpose: link 表示链接，purpose: download 表示下载
@PageKind(sampleCode) 将页面标记为示例代码，显示特殊标题和图标
@PageImage(purpose: card) 设置卡片展示时的图片
@PageImage(purpose: icon) 设置导航栏和页面介绍区的图标
@PageColor 设置页面主题色（支持 green、yellow、purple、orange 等标准色）

特色内容链接

（21:55）用 @Links 在页面顶部展示特色内容：

@Links(visualStyle: detailedGrid) {
    - <doc:GettingStarted>
    - <doc:SlothySample>
}

关键点：

visualStyle 支持 list（简单列表）和 detailedGrid（详细卡片网格）
链接指向文档目录中的其他页面
被链接的页面如果设置了 @PageImage(purpose: card)，会显示卡片图片

自定义主题

（27:04）在 Documentation Catalog 中创建 theme-settings.json：

{
    "theme": {
        "color": {
            "standard-green": "#83ac38"
        },
        "typography": {
            "html-font": "serif"
        }
    }
}

关键点：

文件名必须是 theme-settings.json
color 区域覆盖标准颜色变量
typography 区域控制字体设置
只影响网页部署，Xcode 内文档不受影响
更多自定义选项参考 Swift-DocC 官方文档

核心启发

为开源框架创建产品级文档网站
- 做什么：用 Swift-DocC 为你的 Swift Package 创建与官网风格一致的文档站点
- 为什么值得做：Documentation Preview 让编写过程高效愉悦，自定义主题让文档融入品牌视觉，发布到 GitHub Pages 零成本
- 怎么开始：在 Package 中添加 Documentation Catalog，编写 Markdown 文章，用 xcodebuild docbuild 构建并部署
为团队内部框架建立可浏览的 API 参考
- 做什么：让团队成员能快速查找内部框架的 API 用法和示例
- 为什么值得做：DocC 自动从文档注释生成 API 参考，Quick Navigation 支持快速跳转，比翻源码高效得多
- 怎么开始：为公开 API 编写三斜杠文档注释，用 @Row 和 @Column 组织概念性内容，构建后部署到内网
创建带交互式教程的入门指南
- 做什么：为新用户创建”从零到一”的分步教程，每步包含介绍、代码和预期结果
- 为什么值得做：DocC 的教程格式天然适合引导式学习，比静态 README 更易懂
- 怎么开始：在 Documentation Catalog 中创建 .tutorial 文件，用 @Tutorial 指令定义步骤，每个步骤用 @Steps 和 @Code 展示代码演变
为复杂 API 编写图文并排的详细说明
- 做什么：用网格布局让文档同时展示文字说明和界面截图
- 为什么值得做：@Row + @Column 让图文关系更清晰，比垂直堆叠的排版更易读
- 怎么开始：在 Markdown 文档中使用 @Row 包裹 @Column，调整 size 参数控制列宽比例

关联 Session

Meet DocC documentation in Xcode — Swift-DocC 入门，了解基础文档编写流程
Elevate your DocC documentation in Xcode — 提升 DocC 文档质量的进阶技巧
Build interactive tutorials using DocC — 使用 DocC 构建交互式分步教程

Highlight

核心内容

扩展符号文档化

Documentation Preview 编辑器

丰富的页面布局指令

自定义主题

Quick Navigation

详细内容

为扩展编写文档注释

网格布局

Tab 导航器

嵌入视频

页面元数据

特色内容链接

自定义主题

核心启发

关联 Session

评论