Swift-DocC 现已开源
在 WWDC21 上，Apple 发布了 Swift-DocC，这是一款用于 Swift 框架和包的全新文档编译器。Swift-DocC 提供了一种轻松的方式，让您可以在编写代码的同时编写出色的文档，并为 Swift 代码库生成全面的文档网站。它支持以代码注释形式编写的 API 文档、以 Markdown 编写的长篇概念文章，甚至包含集成图像的逐步教程。
Swift-DocC 已包含在 Xcode 13 工具中，人们已经开始为他们的代码添加更多文档。在 WWDC21 上发布时，一些工程师提到 Swift-DocC 将作为开源发布。而现在，这一天已经到来，并支持多个平台。
Swift-DocC 的开发目标如下
- 与现有开发工具集成。 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 社区中已流行的 Swift 文档注释语法，这些语法在 Jazzy 和 SwiftDoc 等杰出工具以及 Xcode 等 IDE 中都有体现。它还添加了一些新的语法特性。例如，双反引号 ``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 演化流程，首要任务之一是设计与 Swift Package Manager 的集成，使用可扩展的插件。很快，Swift 开发 trunk 快照（对于 Swift 5.5 之后的版本）将包含 Swift-DocC 工具。
要了解更多关于 Swift-DocC 未来发展的信息，请查看论坛上的 Swift-DocC 项目发布公告帖子。
采纳
为了开始使用，Swift-DocC 项目本身生成的文档托管在 swift.org/documentation。更长远的目标包括为更多软件包添加文档，以及迁移标准库和其他文档在 上的文档。这将使社区更容易参与到 Swift 的文档编写和教学中。
参与进来
我们非常欢迎您的经验、反馈和贡献！
- 访问 GitHub 上的 Swift-DocC 开始使用
- 在 swift.org/documentation 上阅读 Swift-DocC 文档（使用 Swift-DocC 编写！）
- 在 使用 Swift 论坛中获取关于使用 Swift-DocC 的帮助
- 在 Swift-DocC 论坛中讨论 Swift-DocC 的实现和开发
- 观看 Apple WWDC21 会议
- 提交错误报告，报告您发现的问题或改进的想法
- 一如既往，欢迎提交 pull request！