如何方便地託管箱子的最新文檔？

Question

我最近在crates.io上發佈了我的第一個箱子，我想知道是否可以更簡單地維護其文檔。

不少箱子的文檔託管在GitHub頁面上，所以我想我會給它一個鏡頭。我創建了一個user.github.io回購，生成了文檔cargo doc，並將它們推送給它。一切正常，文件可以從crates.io查看。

但是，更新它們是不方便的;如果我修改箱子的文檔，我需要：

1. 推動這些變化在包裝箱的回購
2. 產生通過cargo doc
3. 移動的文檔文件更新文檔到GitHub的頁面的文件夾
4. 推docs到文檔的回購

我很確定我沒有做對 - 特別是第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