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

Question

我最近在crates.io上发布了我的第一个箱子，我想知道我是否可以更容易地维护其文档。

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

然而，更新它们很不方便;如果我修改箱子的文件，我需要：

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

我很确定我做得不对 - 特别是第3点。我该怎么做才能简化这个过程？还有更好的办法吗？

Answer 1

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

  

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

     

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

这需要权衡：

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

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

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

一般概念是：

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

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

• Rust, Travis, and Github Pages

• Rust docs on GitHub Pages via Travis

• Automatically Update Github Pages with Travis