4

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

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

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

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

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

4

1 回答 1

6

对于许多 crate，Docs.rs是一个很好的解决方案。它把自己描述为：

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/.... 如果此命令失败，则将令牌打印到 stderr，将其公开。其他不太明显的情况也会在失败时暴露令牌，因此请彻底检查。

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

于 2017-04-07T19:05:20.240 回答