Session 10244 – 运用 Swift-DocC 构建丰厚的文档

本文首发于老司机技能周报 xiaozhuanlan.com/topic/59760…

作者：叶絮雷，Swift Documentation Workgroup 成员，现在上任于字节西瓜视频团队

审核：

• SeaHub：现在任职于腾讯 TEG 计费渠道部，负责建立服务于腾讯系事务的支付体系，主导国内 IAP 前后端相关内容，对 IAP 全体设计有一定的经验；

• 黄骋志：老司机技能轮值主编，现在上任于字节跳动，参与西瓜视频质量与稳定性工作。对 OOM/Watchdog 较为了解并长时间投入

本文是根据 WWDC23 中的 Create rich documentation with Swift-DocC 撰写，主要是引导怎么运用 DocC 的新功用构建更丰厚的结构文档。

前语

Swift-DocC 是一个直接集成到 Xcode 中的文档编译器，答应咱们在源代码中为项目编写和发布丰厚的文档。

咱们能够经过在源代码中编写文档或许经过单独的 Markdown 文件来为代码编写详细的技能文档。

DocC 也能够导出为静态网络托管解决方案，答应直接发布到 GitHub Pages 和 Netlify 等服务。一起生成的文档也将经过 Index 体系会出现在 Xcode 的内置文档窗口中，并集成到了 Xcode 的源代码编辑器中。

这意味着以 DocC 格局编写的文档将主动供给给任何有权拜访源代码的人，而无需任何额定的工作。

自 Swift-DocC 跟着 Xcode 13 一起发布以来，DocC 项目一直是经过 Github 开源库的方法进行的揭露开发。社区的支撑也给 DocC 供给了大量的新功用和改善，如自界说主题、导航、查找、视频支撑等等。

目标方面，现在 DocC 除了支撑 Swift Package 级别的文档也供给了应用程序级别的文档支撑。

语言方面，现在无论运用 Swift、Objective-C 还是两者混合编写的代码都能供给文档支撑。

一起在 Xcode 15 中经过和 DocC 的紧密结合，供给了文档预览编辑器。能够和 SwiftUI 相似，在编写文档的过程中供给实时的渲染视图。

该Feature在上一年8月的 SDWG 会议上进行了评论，想法是供给一个和 SwiftUI Preview 相似的能力

终究在本年的 Xcode 15 上完结了实现，但是其他 IDE 如 VSCode 也是能够经过现在的接口支撑 Live Preview 的

• Documentation Workgroup meeting notes: August 1st 2022

• Add Swift Documentation Preview Support

除此之外，凭借全新的 DocC 指令支撑，如根据网格的布局、视频支撑、自界说页面图标等，甚至彻底自界说的主题装备，咱们能够制作真实体现结构特征的定制文档。

本文将要点评论 Swift-DocC 的一些高级的功用，假如此前对 DocC 不太了解，建议能够看往期内参专题和相关 WWDC 视频：

• WWDC21内参: DocC: 未曾想象的苹果文档

• WWDC22内参: Swift-DocC 新特性

• WWDC21: Meet DocC documentation in Xcode

这里以 SlothCreator 这个在前几年的 Session 中出现的示例项目为例，演示怎么运用 DocC 编写更加丰厚的文档。

SlothCreator 是一个并用于创立办理树懒的软件包。这里首要运用 Xcode 15 中打开该软件包，经过 Build for Documentation 选项咱们能够对当前的文档状态进行一个初步评估。

Swift-DocC 会主动为项目中的相关 API 创立页面，一起也包括前面提到的代码注释，在没有进行过多手动适配的情况下，DocC 是开箱即用的，会供给一个根本的文档页面。

上图为 SlothCreator 的尖端文档页面，经过一句话的摘要开端，然后在 Overview 中概述结构的全部内容。

再往下则是主题部分，主题用于将文档的不同页面组织成逻辑组。

首要，咱们有 Essentials 主题，其中包括针对结构新手的介绍性文档。然后是树懒的创立、树懒的喂食和树懒视图小组。组织良好的主题组是为结构创立可发现和可拜访文档的要害。

扩展文档支撑

在页面的最下面是在 Swift 5.8 东西链中 DocC 中引入的扩展模块文档支撑，这里能够看到 SlothCreator 为 SwiftUI/Image 供给了一个 init 方法并增加了注释。

相关的社区提案原文 Document Extensions to External Types Using DocC

该功用彻底由社区贡献驱动，并触及 Swift-DocC 和 Swift 编译器的协调更改。

文档预览编辑器

咱们能够看到该扩展有一些根本的文档注释，但是和之前的文档比较，它的质量要差一些。

运用 Xcode 15 的文档预览编辑器，咱们将对它增加一些额定的文档。

打开对应的 Swift 文件并敞开文档预览（编辑器右上角敞开 Assistance 形式，并挑选 Documentation Preview）

现在，当咱们在 Swift 源文件、Objective-C 头文件和 Markdown 文件之间移动时，文档预览将坚持活动状态。

在原来简单文档的基础上，咱们进行以下迭代

1. 在摘要后换行增加一段评论内容

2. 继续增加一些代码示例，并标记语言为 Swift

3. 将准备好的图片放入文档目录中，并在文档注释中引证

DocC 会在文档目录中寻找到最合适的图片变种，比方 2x 和 3x 图片、淡色形式图片和深色形式图片等

咱们只需要按照对应的格局命名（eg. iceSloth~dark@2x）并在文档注释中运用原称号引证即可

Swift-DocC 的语法根据 Github Flavored Markdown，但是也供给了一些额定的指令来支撑更多的功用

如 Image 和 Video 指令分别供给了对图片和视频的支撑。

在最初版别的 DocC 中指令只支撑在 Tutorial 格局中运用，跟着社区的反馈，文档工作组终究扩展了它的运用，现在咱们能够在任何地方运用 DocC 指令。

社区 Pitch Supporting more dynamic content in Swift-DocC reference documentation

相关 PR Add @Image and @Video directives to reference documentation with caption support

DocC 指令主要用于额定进行文档的创造性定制，没有一种强制标准约好必须运用。

比方插入图片既能够运用 Image 指令 – @Image(source: String, alt: String?)

也能够运用传统的 GFM 语法()

咱们将经过发现问题并挑选运用一些合适指令来润色 SlothyCreator 的示例代码文章。

在原始的 Sloth Creator 文章中，咱们发现了以下四个问题：

1. 虽然此页面有示例代码，它和任何其他文章看起来是相同

2. 示例代码链接很难辨认和发现

3. 正文内容是围绕两个图画阶段对构建的，图画与它们的阶段没有清晰相关且图片占用了太多的空间

4. 页面底部用 3 张截图展示了不同语言的示例，但是它们之间没有相关且占用了太多空间。

---

关于问题 1 和问题 2，咱们运用 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. The first screenshot shows a sloth map and the second screenshot shows a sloth power picker.")
}

现在 PageKind 只支撑两种类型，article 和 sampleCode，假如有其他更多的需求，能够在 Swift 论坛中进行反馈。

---

关于问题 3，咱们运用 Row 和 Column 指令来重新组织页面内容，能够经过 size 参数来覆盖默许巨细，让咱们更好地控制页面布局。

@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)
    }
}

---

关于问题 4，咱们运用 TabNavigator 指令来重新组织页面内容

TabNavigator 指令包括恣意数量的子 Tab 指令，每个 Tab 指令都有一个标题和内容。

@TabNavigator {
    @Tab("English") { ... }
    @Tab("Chinese") { ... }
    @Tab("Spanish") { ... }
}

---

最后咱们期望运用该文档的受众能够更容易地发现它，所以咱们回到 SlothCreator 文档的尖端页面，经过 Links 指令并界说视觉参数来指向它们。

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

SlothCreator 文档在短时间内经过各种 Dirctive 指令得到了很大的改善，关于各个指令的运用方法能够在以下文档中查询

• Open Source Swift-DocC Documentation

• Apple Swift-DocC Documentation

Tips:

二者现在并无不同，前者经过 Github Action 布置在 Swift 开源项目上

后者为 Apple 的私有布置并装备运用了 Xcode 风格的主题

在 Xcode 中检查的文档默许运用了 Apple 风格的主题，而经过 Swift-DocC-Render 转化得到的 Web 版文档则会运用咱们装备的主题，假如没有进行装备则会运用默许主题。

但是自界说主题不一定是咱们需要定制文档的正确方法，请在运用主题装备前知晓以下事项

1. 主题装备是一个大局网页装备，会影响一切的文档。

假如您想要为单个文档定制，能够运用 Metadata 指令。

2. Swift-DocC 主题是针对网页布置的，在 Xcode 中会被忽略生效。

假如确实期望自界说一起出现在 Xcode 和 Web 中，最好运用指令来完结。

Swift-DocC 中的主题由具有特定称号 “theme-settings.json” 文件界说，咱们能够将其放入文档目录中来生效。

关于 SlothCreator，咱们会自界说它的色彩和字体来匹配对应全体网站的设计。这些定制只是 Swift-DocC 主题的开端，假如有爱好更进一步，能够阅读 Swift-DocC 的相关文档了解。

Swift 5.8 东西链中的 DocC 还供给了全新的快速导航功用，使在页面之间进行导航变得更加容易。

与 Xcode 的 Quick Open 功用相似，它答应咱们经过键盘快捷键并键入其称号进行查找并直接跳转到页面。

Swift-DocC Quick Navigation 也是一个彻底社区驱动的成果

感爱好的同学能够在这里了解更多的上下文 Quick navigation in DocC Render

凭借新的快速导航弹出窗口和现有的导航边栏，Swift-DocC 为阅读在线文档供给了和 Xcode 中阅读文档相同的优异体验。

本文介绍了 Swift-DocC 的进阶运用方法，以及怎么经过指令来定制文档的内容和外观。

从 21 年的开源但是只能根本只能在 Xcode + Swift Package 上运用，到逐渐丰厚功用和对 Web 更友好的布置，以及 DocC Plugin 的一键集成接入，相信 DocC 会成为未来 Swift 生态中十分重要的一部分。

DocC Plugin 现在对 C 系语言的支撑还在继续跟进中 Swift-DocC-Plugin-Mix-Demo

总的来说，我关于本年 DocC 的更新还是十分满意的。一起不少大厂（如字节）内部的部分新结构也已经开端迁移到运用 DocC 进行文档的维护和迭代。

尾声

现在 DocC 的一切重大功用都会在 Swift Forums 上进行揭露评论，并经过双周维度的 Workgroup 会议进行决策。

假如你也期望为 DocC 进行贡献，欢迎提交 PR 或许参与到 Swift Forums 的评论中来。

一些能够参考的优异的 DocC 文档

• The Swift Programming Language

• Swift-DocC

• SwiftUI Tutorial

• ChimeKit