使用 esdocs 生成文档


使用 esdocs 生成文档

esdocs 官网, 博客地址, 示例项目

场景

在尝试过使用 markdown, jsdoc, docz 之后,吾辈终于找到了一个比较满意工具 – esdocs。

期望

  • 开箱即用: 毫无疑问, js 正在把一切事情变得复杂,到处都是大量的配置,永远都学不会开箱即用
  • 支持 jsdoc 注释: 已经熟悉了 jsdoc,所以不太希望切换到其他的注释规范了呢
  • 可配置自定义页: 作为文档 API 列表还算合适,然而首页的话果然还是自定义最好

因为以上的期望,吾辈最终选择了 esdocs。

使用

添加依赖

yarn add -D esdoc esdoc-standard-plugin

初始化配置

创建一个配置文件 .esdoc.json

{
  "source": "./src",
  "destination": "./docs",
  "plugins": [{ "name": "esdoc-standard-plugin" }]
}

当然,如果你使用的命令行是 bash/git-for-bash/cmder 的话,亦可使用命令快速完成

echo '{
  "source": "./src",
  "destination": "./docs",
  "plugins": [{"name": "esdoc-standard-plugin"}]
}' > .esdoc.json

打包

package.json 中添加一个打包文档的 script 命令

"scripts": {
  "docs": "esdoc"
}

然后使用 yarn docs 命令即可打包一份新鲜可用的文档啦

查看

然后打开 docs/index.html 文件即可查看了,下面截张吾辈的工具库 rx-util 生成的文档。

rx-util

总结

感觉是不是很简单,吾辈也是这样认为的呢!后面会整理一份 jsdoc 的标签列表,便于快速查找与一览。


文章作者: rxliuli
版权声明: 本博客所有文章除特別声明外,均采用 CC BY-NC-SA 4.0 许可协议。转载请注明来源 rxliuli !
 上一篇
jsdoc 注释标签一览 jsdoc 注释标签一览
jsdoc 注释标签一览速览表格标签列表 标签 简介 param 参数 returns 返回值 example 示例 test 测试代码 class 类定义 property 类属性定义 语法列表 语法
2019-03-31 rxliuli
下一篇 
使用 jest 和 babel 测试 使用 jest 和 babel 测试
使用 jest 和 babel 测试 博客, GitHub 示例 场景最近想为吾辈的工具函数库 rx-util 添加单元测试,因为目前还在学习 ReactJS,所以最终选择了 Fackbook 家的 jest 进行测试。这里记录一下整个过
2019-03-30 rxliuli
  目录