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

Question

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

很多 crates 的文档都托管在 GitHub 页面上，所以我想我会试一试。我创建了一个 user.github.io 存储库，使用 cargo doc 生成文档并将它们推送到它。一切正常，可以从 crates.io 查看文档。

但是，更新它们很不方便；如果我修改了 crate 的文档，我需要：

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

我很确定我做的不对——尤其是第 3 点。我可以做些什么来简化这个过程？有没有更好的办法？

Answer 1

对于许多 crate，Docs.rs 是一个很好的解决方案。它describes itself 为：

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

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

这需要权衡：

• 文档会自动生成并为您托管，您甚至不必选择加入。
• 提供每个版本的 crate 的文档。
• 如果您有特定于平台的条件编译，则可以显示不同平台的文档。
• 只会记录您的 crate 的 已发布 版本。如果没有新版本，您无法在文档中发布错字。
• 您需要第三方实体继续提供此服务。
• 您无法（目前？）控制使用哪些功能标志。

---

有些人喜欢更好地控制他们的文档，或者不属于 Docs.rs 的目标受众。其中许多案例选择配置其 CI 基础架构以生成文档并将结果推送到某处。

一个常见的实现是使用Travis CI 和GitHub Pages，因为许多项目已经在使用这些服务。可以使用任何 CI 系统和 HTML 托管服务，只要您愿意将两者连接起来。

一般概念是：

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

有些人发布了博客文章，详细说明了他们如何进行设置。我没有验证过其中任何一个都是正常的，但它们可能包含帮助您配置特定解决方案的详细信息。

• Rust, Travis, and Github Pages

• Rust docs on GitHub Pages via Travis

• Automatically Update Github Pages with Travis