Swift Package Index 标志。Swift Package Index

追踪 Swift 6 严格并发检查的数据竞争安全性的采用情况。有多少个包为 Swift 6 做好准备？

自动生成、自动托管和自动更新 DocC 文档

更新： 此博文中的信息已被我们的官方文档取代。请参考文档，而不是这篇博文。

DocC 于 WWDC 2021 推出，是 Apple 推荐的为您的包提供文档的方式。

它易于使用，并且生成的文档看起来很棒。它可以从注释或单独的文章文件中生成文档，这些文章文件以 Markdown 编写，更适合长篇文档。您甚至可以使用它来创建带有图像和逐步说明的美丽互动教程。DocC 可以生成 Xcode 文档归档，也可以生成一组 HTML 和 CSS 文件，您可以将其托管在 Web 服务器上。

当然，拥有一个装满 HTML 的目录只是成功了一半。您的下一个任务是将它托管到在线的某个地方，甚至设置一个 CI 任务来自动化该过程，以便您发布的文档随着开发的进展保持最新。

这就是我们最新的功能将派上用场的地方，我们今天就发布它！

自动生成、自动托管和自动更新

我们的构建系统现在可以生成和托管 DocC 文档，并使其可以从您在索引中的包页面访问。我们只需要一点配置数据，以便我们知道如何最好地构建您的文档。

配置完成后，您将在侧边栏中看到一个新的“文档”链接，并且再也不用担心您的文档了！

The DocC package page showing a link to the auto-generated and hosted documentation.

作为包作者或维护者，您只需做三两件事，Swift Package Index 即可构建和托管您的文档。

  1. 确保您的包可以使用 Swift 5.6 成功构建。您的包也可以支持早期版本的 Swift，但必须使用 5.6 成功构建。
  2. 如果您尚未添加，请将 swift-docc-plugin 文档插件添加到您包的 Package.swift 清单文件中。
  3. 创建一个 .spi.yml 文件并将其提交到您包的存储库的根目录，告诉我们的构建系统哪些目标具有文档。

从那里，我们将处理其他一切。每次您将新提交推送到您的包时，我们都会重新生成您的文档。

添加 Swift DocC 插件

更新： 不再需要将 DocC 插件添加到您的包中。如果您已经添加了它，请随意删除它。如果保留插件或需要将其用于其他目的，我们的构建系统也可以处理，因此无需急于删除它！您需要对项目进行的唯一更改是添加清单文件。

如果您已经在本地使用过 DocC，您可能已经完成了第一步。如果还没有，请将以下行添加到您的 Package.swift 的末尾

#if swift(>=5.6)
  // Add the documentation compiler plugin if possible
  package.dependencies.append(
    .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0")
  )
#endif

使插件依赖项有条件意味着即使您的清单的 swift-tools-version 适用于早于 5.6 的 Swift 版本，也不会发生任何中断。当然，如果您的包仅支持 Swift 5.6 及更高版本，则这是不必要的。

添加 Swift Package Index 清单文件

然后，在您的存储库的根目录中创建并提交一个名为 .spi.yml 的清单文件，如下所示

version: 1
builder:
  configs:
    - documentation_targets: [Target]

此文件告诉我们的构建系统为目标 Target 生成文档。您通常会将此设置为您包的主要（或唯一）目标，但也可能是一个包含文档 Markdown 文件的专用目标。

您还可以指定多个目标，我们将在托管文档中添加一个目标切换器，以便人们可以轻松找到您的所有文档！

文档平台

默认情况下，我们将使用 macOS 生成文档。如果您的包要求为特定平台（例如 iOS）运行文档生成，您也可以指定平台

version: 1
builder:
  configs:
    - platform: ios
      documentation_targets: [Target]

自动更新频率

为了控制我们的构建服务器执行的处理量，我们最多每 24 小时仅为每个包构建一次默认分支。因此，当您推送配置文件上线时，系统将生成该组文档，但之后需要 24 小时才能再次运行生成过程。如果在此期间有任何提交，我们将在周期重置时从最新的提交创建文档。

Hosted documentation for the DocC package shown in the context of the Swift Package Index with a header above the documentation.

早期采用者！

注意： 我们要感谢以下软件包作者如此早期地加入我们的文档托管功能。该功能现已完全发布且稳定，可供所有软件包作者使用。有关更多信息，请参阅我们的 SPIManifest 文档。

您可能在本周早些时候看到了征集具有 DocC 兼容文档的软件包作者的呼吁，我们很高兴地说，我们有 20 个软件包已经添加了配置文件，并且它们的文档由我们托管！为什么不看看它们呢？

如果您维护我们在索引中的 4,600 多个包之一，请添加您的配置文件以选择让您的文档托管在 Swift Package Index 上，我们将处理其他一切。如果您有任何问题，请加入我们的 Discord 或提出 issue。

后续步骤

我们为我们在这里构建的内容感到自豪，但我们尚未完成此功能。

在我们的讨论论坛上，有一篇关于我们接下来要处理的事情的总结，但总结来说，这是我们计划接下来要做的事情

  • 带有稳定 URL 的版本化文档。您将能够阅读您在项目中使用的确切版本的包的文档。
  • 在文档版本之间轻松切换。一旦我们有了版本化文档，我们计划明确您正在阅读的文档来自何处。如果您正在查看默认分支文档，您将能够看到这一点。如果您正在查看标记版本，也是如此。我们还将使在每个包的文档集之间切换变得容易。

关于此博客

Swift Package Index 是 Swift 包的搜索引擎和元数据索引。我们的主要目标是帮助您更好地决定您在应用程序和项目中包含的依赖项。如果您是新来的，最好的入门方法是搜索包。