如何在 Github 页面上托管 Swift 库文档

来源丨小集

原文发表于 1 月 28 日，点击阅读原文跳转链接

https://rhonabwy.com/2022/01/28/hosting-your-swift-library-docs-on-github-pages/

Xcode 13.3 的 beta 版本已经发布。随之而来的是 Swift 5.6 的发布版本和 5.6 版本支持的一系列简洁的附加功能。这里有我密切关注的两个功能：插件能够扩展 Swift 包管理器中可用的命令，以及新增的 Apple 去年宣布并开源的文档编译器工具 (DocC) 中的静态托管选项.

这两个功能与 swift-docc-plugin 的初始版本一起出现，这是一个 Swift 包管理器的插件，它增加了使用命令 swift package generate-documentation 在命令行上生成文档的能力。在进一步讨论之前，应该指出，当 DocC 团队将其放在一起时，他们知道很多人希望将他们的内容作为静态 HTML 来托管 - 所以他们花了些时间研究如何做到这一点，并且最好最重要的是——他们在 github 页面上托管了 这个文档（我假设使用他们自己的工具来做到这一点）。以下文章都来自 git 存储库中的内容，托管在 GitHub 页面上：

• Getting Started with the Swift-DocC Plugin

• Generating Documentation for a Specific Target

• Previewing Documentation

• Generating Documentation for Hosting Online

• Publishing to Github Pages

这非常好——我使用以下命令推送了我一直在研究的 Lindenmayer 库的文档：

swift package \
    --allow-writing-to-directory ./docs \
    --target Lindenmayer \
    generate-documentation \
    --output-path ./docs \
    --emit-digest \
    --disable-indexing \
    --transform-for-static-hosting \
    --hosting-base-path 'Lindenmayer'

但是……您应该注意一些小问题。

首先，静态托管内容的能力并不意味着它是静态内容。DocC 在管理文档方面与几乎所有类似的先前工具不同。Doxygen、JavaDoc、Sphinx、Hugo、AsciiDoc 和其他工具阅读源代码并生成 HTML，这不是 DocC 想做的事情。虽然为静态托管转储的内容最终包括 HTML，但 DocC 依赖于其他两个关键组件来完成其工作。它从编译器生成所谓的符号图开始。这是一个包含源代码中所有符号（类型、属性、类型别名等）以及它们之间的关系的文件。然后，DocC 调整该符号图，更具体地说，将其与目录中的其他（创作的，非自动的）markdown 文件混合 - 这称为文档目录。如果文档目录或原始源中的 markdown 文件没有为符号图中的关系提供内容或结构，那么 DocC 会建立一个默认集，并尝试提供一个默认结构。对于它的价值，这个默认的内容集是“没有可用的概述”的来源。生成的组合被序列化为一堆 JSON 文件，存储在文件系统中。这些 JSON 文件包含渲染内容所需的信息——但内容渲染的核心来自另一个项目，一个基于 Vue 的 JavaScript 单页应用程序：swift-docc-render。

JSON 文件允许这些文档内容更容易被浏览器使用。

回到 DocC 和静态托管——这意味着转储到“docs”目录中的内容不仅仅是纯 HTML——它是 Javascript 以及所有相关内容。这样做的效果是，虽然看起来您可以直接打开该目录中的 index.html 并查看您的内容，但它不起作用。相反，您只会看到一个空白页面，如果您碰巧查看 JavaScript 控制台，您会看到错误报告，报告在此服务器上未找到请求的 URL。

这也意味着内容在您推送的 GitHub 页面的根目录中不可用。我的 Lindenmayer 项目的根目录是 https://heckj.github.io/Lindenmayer/ —— 但是直接去那里看并没有显示任何东西。相反，你需要去几个目录：https://heckj.github.io/Lindenmayer/documentation/lindenmayer/。另请注意，库的名称是小写的。我尝试的第一件事是https://heckj.github.io/Lindenmayer/documentation/Lindenmayer/，它也不起作用。

关键是要知道，您需要让用户指向的 URL 上扩展了 documentation/your_library_name_lowercased。名称的第一个重复是 github repo。例如，对于 swift automerge 库，reposity 是 automerge-swift，而包名是 automerge。然后 github 上托管页面的 URL 变为：https://automerge.github.io/automerge-swift/documentation/automerge/。

边注：

我在上面提供的示例生成文档命令中包含可能不需要的额外位，特别是 --emit-digest 选项。此选项在内容的顶层 (linkable-entities.json) 生成一个额外的 JSON 文件，其中包含库中所有（公共）符号的列表。我有意选择将此文件包含在我托管在 Github 页面上的内容中（位于 http://heckj.github.io/Lindenmayer/linkable-entities.json）
，尽管（据我所知）显示 HTML 内容的单页应用程序并未使用它。正式的内容定义（编写为 OpenAPI 规范）在位于 https://github.com/apple/swift-docc/blob/main/Sources/SwiftDocC/SwiftDocC.docc/Resources/LinkableEntities.json 的 DocC 存储库中定义。简短的形式是它提供了所有符号的列表，我可以使用这些符号来引用该内容中的符号，否则这些符号很难获得。

如果你好奇这是什么样子，试试下面的命令（假设你已经安装了 curl 和 jq）：

curl -sL http://heckj.github.io/Lindenmayer/linkable-entities.json | jq '.[].referenceURL' -r.

输出类似于：

doc://Lindenmayer/documentation/Lindenmayer/RewriteRuleLeftDirectRightRNG/description
doc://Lindenmayer/documentation/Lindenmayer/SceneKitRenderer/generateScene(lsystem:)-5b948
doc://Lindenmayer/documentation/Lindenmayer/RenderCommand/draw-swift.type.property
doc://Lindenmayer/documentation/Lindenmayer/RewriteRuleLeftDirectDefines/CustomStringConvertible-Implementations

这些是 DocC 中使用的完整参考链接，其中一部分参考链接可以用作文档目录中降价文件中的符号。

<doc://Lindenmayer/documentation/Lindenmayer/SceneKitRenderer/generateScene(lsystem:)-5b948>

映射到符号：

``Lindenmayer/SceneKitRenderer/generateScene(lsystem:)-5b948``

在少数情况下，那些小的散列扩展（示例中的 -5b948 位）很难找到。Xcode 在使用代码完成方面做了合理的工作，但我发现了一些难以确定的错误。这个包含所有符号的 JSON 文件正是我获得完整列表所需要的。

我还没有想出将这些 doc:// 资源 URL 转换为 Web URL 的方法，但我有一个想法，有一种方法可以在库构建时实现交叉链接文档的能力，或依赖于其他库。也许这就是这个摘要的最终目的，但如果是这样的话——它还不是 DocC 中易于使用的功能。我仍在探索 DocC 的内部结构，但有一个解析器的想法——它可以是一个外部进程或服务——它为 DocC 提供此映射以构建它需要启用该功能的链接。

-End-

最近有一些小伙伴，让我帮忙找一些 面试题 资料，于是我翻遍了收藏的 5T 资料后，汇总整理出来，可以说是程序员面试必备！所有资料都整理到网盘了，欢迎下载！