[譯] 討論 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 2017、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、前端、後端、區塊鏈、產品、設計、人工智慧等領域，想要檢視更多優質譯文請持續關注 掘金翻譯計劃、官方微博、知乎專欄。