[译] 讨论 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、前端、后端、区块链、产品、设计、人工智能等领域，想要查看更多优质译文请持续关注 掘金翻译计划、官方微博、知乎专栏。