如何方便地托管一个crate最新的文档？

Question

我最近在crates.io上发布了我的第一个crate，想知道是否有更简便的方式维护它的文档。

很多crate的文档都托管在GitHub页面上，所以我想试一下。我创建了一个user.github.io库，用cargo doc生成文档并将其推送到该库。一切都运行良好，文档可以从crates.io查看。

然而，更新文档很不方便；如果我修改crate的文档，我需要：

1. 将这些更改推送到crate的存储库
2. 通过cargo doc生成更新的文档
3. 将文档文件移动到GitHub页文件夹
4. 将文档推送到文档存储库

我相信我没有做对-特别是第3点。我能做什么来简化此过程？有更好的方法吗？

- ljedrz

Answer 1

对于许多的板条箱来说，Docs.rs 是一个很好的解决方案。它 自我描述 为：

Docs.rs（以前是 cratesfyi）是一个开源项目，用于托管 Rust 编程语言的板条箱文档。

Docs.rs 使用 Rust 编译器的每夜版本自动构建在 crates.io 上发布的板条箱文档。

这有一些权衡：

• 文档会自动生成并为您托管，您甚至不需要选择加入。
• 每个版本的板条箱文档都可用。
• 如果您有特定于平台的条件编译，可以显示不同平台的文档。
• 只有发布的板条箱版本才会被记录文档。您无法发布文档中的笔误而不进行新版本发布。
• 您需要依赖第三方实体继续提供此服务。
• 您目前无法控制使用哪些功能标志。

---

有些人更喜欢对他们的文档进行更多的控制，或者不适合 Docs.rs 的目标受众。在许多这种情况下，他们选择配置 CI 基础设施来生成文档并将结果推送到某个地方。

一个常见的实现方式是使用 Travis CI 和 GitHub Pages，因为许多项目已经使用了这些服务。任何 CI 系统和 HTML 托管服务都可以使用，只要您熟悉连接这两个服务。

一般的概念是：

1. 在 CI 中添加一个构建文档的步骤。
2. 当检测到特定类型的构建时，将生成的文档推送到托管服务。
   • 可能的构建类型选择：任何分支；主分支；一个标签；等等。
   • 注意避免暴露任何凭据。一个常见的错误（我自己也犯过）是使用类似 git push https://${GH_TOKEN}@github.com/... 这样的命令。如果此命令失败，则会将token打印到stderr，从而使其暴露给全世界。其他不太明显的情况也会在失败时暴露令牌，因此请仔细检查这些情况。

有些人已经发表了博客文章详细介绍他们如何设置。我没有验证这些方案是否可行，但它们可能包含有助于配置特定解决方案的细节。

• Rust、Travis和Github Pages

• 通过Travis在Github Pages上发布Rust文档

• 使用Travis自动更新Github Pages

- Shepmaster

---

值得注意的是，Travis CI现在已经内置了对GitHub pages部署的支持——您不再需要自定义的部署脚本。 - user355252