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

Question

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

很多板条箱的文档都托管在 GitHub 页面上，所以我想我应该尝试一下。我创建了一个 user.github.io 存储库，生成文档cargo doc并将其推送到其中。一切工作正常，可以从 crates.io 查看文档。

但更新不方便；如果我修改板条箱的文档，我需要：

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

Answer 1

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

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

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

这需要权衡：

有些人更喜欢对其文档有更多的控制权，否则就不属于 Docs.rs 的目标受众。其中许多案例选择配置其 CI 基础设施来生成文档并将结果推送到某个地方。

一种常见的实现是使用Travis CI和GitHub Pages，因为许多项目已经使用这些服务。任何 CI 系统和 HTML 托管服务都可以使用，只要您能够轻松连接两者即可。

总体概念是：

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

有些人发表了博客文章，详细介绍了他们如何设置。我尚未验证其中任何一个是否正常，但它们可能包含可帮助您配置特定解决方案的详细信息。