Apple 又开源一 Swift 项目，相当实用-技术圈

在 WWDC21 上，Apple 发布了 Swift-DocC，这是一种用于 Swift 框架和包的新文档编译器。Swift-DocC 提供了一种轻松的方式来编写出色的文档以及您的代码，并为 Swift 代码库生成全面的文档网站。它支持编写为代码注释的 API 文档、用 Markdown 编写的长篇概念文章，甚至带有集成图像的分步教程。

Swift-DocC 包含在 Xcode 13 工具中，它有以下几个开发目标：

与现有的开发工具集成。Swift-DocC 工具旨在无缝集成到现有的开发人员工作流程中，并直接在流行的编码工具和 IDE 中工作。使用 Swift-DocC 创作文档将很容易适应开发人员已经使用的相同版本控制过程。
简化创作丰富的参考文档。参考文档是描述 API 行为的重要资源，也是第三方开发人员的最佳实践。通常，API 之间的链接对于解释它们的使用至关重要，因此使这些链接易于创作和验证是一个关键目标。
鼓励高水平的技术文章。从历史上看，开发人员将高级说明文档与 API 文档分开编写和维护，这使得这些内容最初不太可能被编写，并且可能会过时。通过提供用于在代码旁边创作这些高级内容的工具，以及 API 和概念文档的轻松互连，我们的目标是查看更多包含在包和框架中的概念文档。
为新用户添加丰富的教程。教程可以通过轻松创建友好的学习体验来帮助提升第三方包的 Swift 生态系统，这对于不熟悉 API 的开发人员来说尤其有用。像文章一样，教程可以很容易地包含在主要的文档工作流程中
轻松将文档连接在一起。组织良好的文档会更容易找到。另一个关键目标是为开发人员提供一种直观的方式来将文档组织成逻辑组并编写指向其他页面的链接。

概述

Swift-DocC 包含帮助开发人员在许多平台（包括 macOS 和 Linux）上编写和生成文档的工具和库，其目标是通过 Swift 工具链支持所有平台。docc 命令行工具已经集成在 Xcode 13 中，其架构方式可以与其他构建系统（如 SwiftPM）集成。开源项目由几个组件组成，其中一些组件本身可能对构建其他开发人员工具很有趣。组件包括：

Swift-DocC — 处理源文件注释、独立 Markdown 文件和相关资产以生成机器可读 JSON 存档的文档编译器工具。
Swift-DocC-Render — 一种基于 JavaScript 的 Web 应用程序，可呈现已编译的 DocC 档案。
Swift-Markdown — 一个可以在 Swift 中轻松解析 Markdown 语法的库。
SymbolKit — 一个 Swift 库，用于解析 Swift 编译器发出的符号图文件。这些文件封装了有关模块 API 的信息，包括它们的文档注释。

该工具可以理解 Swift 社区中已经在 Jazzy 和 SwiftDoc 等杰出工具以及 Xcode 等 IDE 中流行的 Swift 文档注释语法。它还添加了一些新颖的语法功能。例如，双反引SymbolName语法在符号之间创建链接。一个例子：

源文件文档注释

/// A model representing a sloth.
/// 
/// You can create a sloth using the ``init(name:color:power:)`` initializer, or
/// create a randomly generated sloth using a ``SlothGenerator``:
///
/// ```swift
/// let slothGenerator = MySlothGenerator(seed: randomSeed())
/// let habitat = Habitat(isHumid: false, isWarm: true)
/// do {
///     let sloth = try slothGenerator.generateSloth(in: habitat)
/// } catch {
///     fatalError(String(describing: error))
/// }
/// ```
public struct Sloth { … }

渲染的结果

下一步

与 Swift 工具集成

构建文档应该像构建代码一样简单。为此，接下来的步骤将包括将 Swift-DocC 与核心 Swift 工具一起使用，以便所有 Swift 开发人员可以从项目一开始就轻松地记录他们的代码。

与核心 Swift 工具的其他组件一样，该项目将遵循 Swift Evolution 流程，首要任务之一是使用可扩展插件设计与 Swift Package Manager 的集成。很快，Swift 开发主干快照（适用于 Swift 5.5 之后的版本）将包含 Swift-DocC 工具。

采用

正在 swift.org/documentation 上托管为 Swift-DocC 项目本身生成的文档。长期目标包括向更多包添加文档，以及跨 Swift.org 迁移标准库和其他文档的文档。这将使社区更容易参与 Swift 的记录和教学。