[譯] 討論 JS ⚡：文檔

• 原文地址：Let's talk JS ⚡: documentation
• 原文做者：Arek Nawo
• 譯文出自：掘金翻譯計劃
• 本文永久連接：github.com/xitu/gold-m…
• 譯者：Starrier
• 校對者：wznonstop, SHERlocked93

若是你曾經參與過開源項目，或大到須要文檔的項目，那麼你應該知道編寫一個合格的文檔是多麼的重要。此外，文檔須要始終保持最新，而且應包含全部公共 API。所以，如何製做完美的文檔呢？本文的目標就是用 JS 的風格來解決這個問題！⚡

Photo by rawpixel / Unsplash

並且只有兩種方法...

爲你的項目編寫文檔的方法只有兩種。即：本身寫或者自動生成。這裏沒有黑魔法，也別無他法.

那麼，咱們先開始研究「本身寫文檔」。在這個場景中，你能夠輕鬆地建立漂亮的文檔站點。固然，這將須要你作更多的工做，但若是你認爲這是值得的，那就去作吧。👍固然，你須要考慮保持你的文檔的實時性，這也會形成額外的時間花費。可定製化是最大的優點。你的文檔可能會使用 markdown（最多見的 GFM）編寫的 — 它只是一種標準。你可讓它看起來很漂亮，若是你正在建立 OSS 的話，這一點很重要。有一些庫能夠幫助你完成這項任務，以後咱們將會深刻了解它們。

接下來，咱們能夠選擇從代碼自己生成文檔。很明顯，這也不是那麼直截了當的事情。首先，你必須使用像 JSDoc 這樣的工具，以 JavaDoc-like 註釋的形式編寫文檔。因此，並非說能夠直接就生成文檔。如今 JSDoc 已經很優秀了。個人意思是，看看它的官方文檔，看看你能使用多少標籤。此外，現代代碼編輯器將獲取你的類型定義和其餘描述，在開發過程當中幫助你使用自動完成和彈出文檔的功能。在你寫簡單的 markdown 時，是不會實現這種效果的。固然，你須要單獨寫諸如 README 這樣的文件，而生成的文檔則會有些程序化，但我認爲這不是什麼大問題。

選擇正確的工具...

所以，假設你已經決定手動建立文檔（或者應該說是用鍵盤），並且是使用 markdown（或者你只是從其餘地方瞭解到了 markdown）。如今，你可能須要一個稱爲 renderer 的工具，它將把你的 MD（markdown）轉換成 HTML、CSS 等漂亮的組合。這是在你不只僅想把它發佈到 GitHub、GitHub 的 wiki 上時的方案。或者你想讓 MD 附加一個額外的 reader（就像這樣）。如今，爲了解決這個任務（IMHO），我將爲你列出一些最好的工具。😉

Docsify

Docsify 登陸界面

Docsify 是一個神奇的文檔站點生成器。它很好地完成了文檔生成的任務。重要的是，它能夠動態地呈現你的文檔，這意味着你無需將 MD 解析爲 HTML — 只須要將你的文件放在正確的位置便可！除此之外，Docsify 有大量插件和一些主題可供選擇。它也有很好的文檔記錄（就像文檔生成器同樣）。當我本身項目的文檔使用這個工具時，我可能會有些偏見。它惟一的問題是（至少對我來講）與 IE 10（正如其在主頁上所說）的兼容性不是很好（可是他們正在嘗試進行兼容），並且它對相關連接缺乏必要的支持。

Docute

Docute v4 文檔

Docute 是一個相似於 Docsify 的工具，但它有一個可愛的名字。最新的版本（v4）相比上一個版本要少一些文檔，同時也進行了必定程度的簡化。生成的文檔看起來簡約而優雅。可使用 CSS 變量 定製主題。Docute 不像 Docsify 那樣擁有強大的插件系統，但它有着本身的優點。它創建在 Vue.js 之上，這致使包的大小相比於 Docsify 要大些，但擴展性好了不少。好比，在你的 MD 文件中，你可使用一些內置的 Vue 組件，甚至你本身的組件。

Slate

Slate 文檔

Slate 多是在 GitHub 上記錄你的項目以及小星星數量的領頭羊（~25,000）。它的文檔清晰，語法可讀性好，且有 everything-on-one-page 的特色。還具備很是可靠的 GH wiki 文檔。它容許深度主題化 ，但由於文檔提供的信息很少，因此你須要本身去源碼挖掘。遺憾的是，它的可擴展性不好，但勝在功能豐富，對於那些須要 REST API 文檔的人來講，這彷佛是一個不錯的選擇。請記住，Slate 生成的是靜態 HTML 文件，而不是在運行中動態生成文件

Docusaurus 登陸界面

Docusaurus

Docusaurus 是一個易於維護開源文檔生成網站的工具。它是由 Facebook 建立的，使用的是 — 沒錯，就是它 — React。它能夠將 React 組件和庫輕鬆地轉換或集成爲一個總體來建立自定義頁面。無需其餘工具，它還能夠創建額外的 blog 直接整合到你的文檔網站，甚至無需其餘工具！它能夠與 Algolia DocSearch 很好地集成，使你的文檔易於導航。就像 Slate 同樣，它會生成靜態 HTML 文件。

VuePress 登陸界面

VuePress

VuePress 是一個 Vue 驅動的靜態站點生成器，由 Vue.js 的創始人開發。這也是生成 Vue.js 官方文檔的可靠工具。做爲一個生成器，它有很是友好的文檔。它還具備一個強大的插件和主題系統，固然也繼承了優秀的 Vue.js。uePress 宣稱其對 SEO 友好，這是由於它生成並輸出的是 HTML 文件。

GitBook 登陸界面

GitBook

GitBook 是用於編寫 MD 文檔和文本的工具。它爲你提供了一個在線編輯器和免費 .gitbook.io 域名體驗。毫無疑問，在線編輯器很棒，可是涉及到佈局，它並無太多的可定製性。該編輯器還有它的遺留桌面版本。但除非你是在作一個開源的項目，不然你須要爲此付費。

生成器！

既然咱們已經介紹了最好的文檔製做工具，那咱們接下來開始使用生成器，好不？生成器主要容許你從帶註釋的代碼中建立文檔。

JSDoc 登陸頁面

JSDoc

JSDoc 多是 JS 最明顯和最有名的文檔生成器。它支持很是多的標籤，而且對幾乎全部的編輯器和 IDE 自動完成功能友好。它的輸出可使用多種主題進行定製。而且主題的種類很是多。更有意思的是，使用這個和其餘生成器，你能夠輸出 markdown，以便以後與上面所列的任何文檔工具一塊兒使用。

TypeDoc 登陸頁面

TypeDoc

TypeDoc 可視爲 TypeScript 的 JSDoc。它榜上有名的主要緣由是，支持 TS 類型的文檔生成器不多（或者說沒有）。經過使用該工具，你能夠基於 TypeScript 類型系統來生成文檔，包括接口和枚舉等結構。遺憾的是，它只支持一小部分 JSDoc 標記，沒有 JSDoc 這樣的大社區。所以，它沒有太多的主題，文檔匱乏。IMO 有效使用該工具的最佳方法是使用 markdown 主題插件，並使用其中一個文檔工具。

ESDoc 登陸界面

ESDoc

ESDoc 在功能上與 JSDoc 類似。它支持相似於 JSDoc 的註釋標籤。它對文檔代碼風格測試或覆蓋測試提供了可選的支持。它有大量的插件集合。此外，還有一些針對 TypeScript、Flow 和 markdown 輸出的概念驗證插件。

Documentation.js

Documentation.js 是現代文檔生成器，它能夠輸出 HTML、JSON 或 markdown，具備極大的靈活性。它支持 ES 201七、JSX、Vue 模版和 Flow 類型。他還能進行類型推斷以及原生 — JSDoc 標記。它有基於 underscore 模版的深度主題選項。遺憾的是，（對我來講）它不支持 TypScript。😕

DocumentJS 登陸界面

DocumentJS

DocumentJS 是文檔生成的解決方案，它不像上面的競爭對手那麼受歡迎。支持大多數 JSDoc 和 Google 閉包編譯器標記，還可以添加自定義的附加功能。它默認只生成可主題化的 HTML，但具備很強的擴展性。

不同的內容。。。

上面我列出了一些標準文檔工具和生成器。固然，它們能夠一塊兒用來建立好的文檔。可是我想再給你推薦一個工具。你據說過 literate programming 麼？也就是說，你能夠使用 markdown 語法來寫註釋，並經過它來生成代碼。它真的把你的代碼變成了詩。

Docco 登陸界面

而後，你使用像 Docco 這樣的工具將你的 markdown 註釋代碼轉換爲帶有代碼片斷的 markdown。我能夠說這是新的嘗試。😁

你都知道了 😉

我但願這篇文章至少能讓你在建立文檔時輕鬆一點。上面這個清單包含了質量頂尖而且維護良好（到目前爲止）的項目。若是你喜歡這篇文章，請考慮分享它，你能夠在 Twitter 上關注我，或者訂閱下面的郵件列表來獲取更多優秀的文章。🦄

若是發現譯文存在錯誤或其餘須要改進的地方，歡迎到 掘金翻譯計劃 對譯文進行修改並 PR，也可得到相應獎勵積分。文章開頭的 本文永久連接 即爲本文在 GitHub 上的 MarkDown 連接。

---

掘金翻譯計劃 是一個翻譯優質互聯網技術文章的社區，文章來源爲 掘金 上的英文分享文章。內容覆蓋 Android、iOS、前端、後端、區塊鏈、產品、設計、人工智能等領域，想要查看更多優質譯文請持續關注 掘金翻譯計劃、官方微博、知乎專欄。