Unidoc 是一款用于 Swift 语言的可扩展文档引擎。Unidoc 可以被视为 Apple 本地 DocC 编译器的多目标模拟。它专为长期存在的中心化文档索引而设计，这些索引存储、链接并为多个 Swift 包的多个文档版本提供服务。

Unidoc 为 Swiftinit 开源包索引提供支持！

Unidoc 支持 Linux 和 macOS。Unidoc 需要 Swift 6.0。

我们为以下平台提供预构建的二进制文件

请按照我们的快速入门指南学习如何设置本地 Unidoc 服务器。

Unidoc 支持 UCF 符号链接语法 —— DocC 符号链接语法的超集 —— 它支持多组件路径、跨模块引用和类型签名消除歧义。

Unidoc 文档编译器可以在 CI 模式下运行，以验证文档并在诊断出文档错误（例如断开的链接）时使管道失败。

Unidoc 编译器可以诊断所有断开的符号链接，包括对包依赖项和标准库中符号的引用。

我们为 GitHub Actions 提供了 swift-unidoc-action。

-   name: Validate documentation
    run: |
        unidoc compile \
            --swift-toolchain $SWIFT_INSTALLATION \
            --ci fail-on-errors \
            --project-path .

Unidoc 可以在文档中渲染 SwiftPM 代码片段，并带有链接的 IDE 风格代码引用和悬停工具提示。

请查看 swiftonserver.com，它使用 Unidoc 作为其渲染后端，以查看代码片段的实际应用示例。

Unidoc 服务器旨在无限期地存储版本化的文档。为了实现这一点，Unidoc 使用了一种稳定的二进制符号图格式，该格式可能比等效的 DocC 归档文件小两个数量级。

以下是（臭名昭著的）SwiftSyntax 包在 508.0.1 版本的比较

DocC 数字来源于 Slack

您可以从符号图归档文件重新生成 Unidoc 文档，而无需从包源重新编译文档，这在历史上是 DocC 工作流程中的一个主要瓶颈。在许多情况下，这意味着即使底层符号图是由旧版本的 Unidoc 编译的，您也可以轻松升级 Unidoc 文档以利用新功能。

Unidoc 数据库使用蜂窝架构，允许您在整个包索引中错开文档升级，而无需使服务器脱机。

Unidoc 可以验证和解析跨包符号链接，包括指向标准库中符号的链接。这意味着您可以在文档中链接到 String，Unidoc 将自动生成指向 String 标准库文档的链接。

也支持正常的“IDE 风格”符号引用，例如函数签名中指向 Int 的链接。

Unidoc 可以直接在扩展类型的文档中显示扩展，包括第三方扩展。这意味着您可以从 swift-nio 文档本身查看源自 swift-nio-ssl 和 swift-nio-http2 等包的 Channel 成员。

在未来，我们希望支持对扩展文档中显示的第三方扩展进行更细粒度的控制。

由于 Unidoc 是一个多包文档引擎，它可以跟踪和显示从上游依赖项（包括标准库）中的协议继承的符号，而存储成本可忽略不计。这意味着第三方库中符合 Sequence 等协议的类型可以在其成员列表中显示和链接到 Sequence API。

Unidoc 服务器维护其索引中所有文档的组合数据库。这允许 Unidoc 按需服务（或重定向）单个符号页面，而不是要求客户端下载庞大的 Vue.js 索引以进行客户端渲染。这为客户端提供了更好的性能，并大大减少了服务器上文档升级时的缓存抖动。

Unidoc 生成轻量级的 HTML 文档，该文档使用 CSS 进行大部分布局和交互，并提供非常少量的额外资源。这意味着 Unidoc 页面是响应式的、可访问的、缓存友好的，并且以最小的内容布局偏移 (CLS) 渲染。

Unidoc 符号图包含由 SwiftSyntax 计算的换行标记，这允许 Unidoc 以可读的、自动换行的格式显示长函数签名。这使得扫描具有复杂签名的长符号列表变得更加容易，例如 SwiftSyntax 的 AccessPathComponentSyntax 的成员列表。

Unidoc 服务器现在可以查询旧版本（和预发布版本）中符号的后继者，并显示一个横幅，将访问者引导到其包最新稳定版本中的对应符号。此链接特定于符号，并带有相应的 <link rel="canonical"> 元素和 HTTP 标头。

示例：https://swiftinit.org/docs/swift-nio:2.57.0/niocore/eventloopgroup

Unidoc 能够以 300 Multiple Choice 状态代码提供符号消歧义页面。

虽然您应该尽可能避免创建歧义符号链接，但它们是 API 演进和添加重载时的自然发生现象。

示例：https://swiftinit.org/docs/swift-certificates/x509/policyevaluationresult.failstomeetpolicy(reason:)

Unidoc 可以计算每个包和每个模块的文档覆盖率。您可以在包和模块页面上以饼图可视化形式查看覆盖率级别；有关示例，请参阅 swift-atomics 的包页面。

Unidoc 可以通过查询 GitHub API 定期索引 Git 标签。此功能需要GitHub 应用程序注册和应用程序密钥，并且默认情况下未启用。如果底层符号图包含源映射信息，Unidoc 还可以从 GitHub 加载存储库元数据，并使用它来生成指向 GitHub 上源代码的永久链接。

即使 GitHub 集成不可用，Unidoc 编译器默认情况下也会构建带有源映射的符号图归档文件。

当 GitHub 集成可用时，Unidoc 可以使用社交身份验证，允许用户使用其 GitHub 帐户登录并执行管理操作。

随着 Swiftinit 索引的增长，我们希望允许包维护者声明其包的所有权，并通过 Swiftinit 网站直接管理其文档。

Unidoc 可以为像 Googlebot 这样的搜索爬虫生成、更新和提供站点地图文件。这允许搜索引擎发现和索引您的文档，并使用户更容易找到您的包。

Unidoc 将努力为包中的每个符号生成 <meta> 描述，即使该符号没有文档。

Unidoc 避免生成同一文档的多个副本，这可能会阻碍在搜索引擎中的可见性。