jsDoc开发文档生成

大家好，欢迎来到IT知识分享网。

提示：文章写完后，目录可以自动生成，如何生成可参考右边的帮助文档

前言

提示：在使用前确定你的电脑已安装node环境。

JSDoc 3 是一个用于 JavaScript 的API文档生成器，类似于 Javadoc 或 phpDocumentor。可以将文档注释直接添加到源代码中。JSDoc 工具将扫描您的源代码并为您生成一个 HTML 文档网站。

一、基础使用

1.安装JsDoc

npm install -g jsdoc

也可以使用局部安装。使用 jsdoc 查看是否安装成功。

确认安装成功后直接使用:

jsdoc file.js

此时效果图如下所示：

可以看见已生成开发文档，文档的注释可以参考JSDoc 入门 | JSDoc中文文档 | JSDoc中文网。

二、使用模板

1，全局安装jsDoc和docdash

npm install jsdoc -g npm install docdash

2.在项目中添加文件jsdoc.json，其中配置如下

{ "tags": { "allowUnknownTags": false }, "source": { "include": "./js", // 表示需要读取的文件名 "includePattern": ".es.js$", // 表示该文件夹下以es.js为后缀名的文件 "excludePattern": "(node_modules/|docs)"//需要排除的文件 }, "plugins": ["plugins/markdown"], "opts": { "template": "./node_modules/docdash", // 模板地址 "encoding": "utf8", "destination": "./doc/", // 生成文件的名字，可自定义 "recurse": true, "verbose": true }, "templates": { "cleverLinks": false, "monospaceLinks": false }, "docdash": { "sort": true, "search": true } }

此时效果图如下所示：

3，ink-docstrap模板

安装ink-docstrap

npm i ink-docstrap npm i taffydb 

"opts": { "template": "./node_modules/ink-docstrap/template/", "encoding": "utf8", "destination": "./docs/", "recurse": true, "verbose": true },

此时效果图如下所示：

此时你可以通过更改主题来修改主题色：

"opts": { "template": "./node_modules/ink-docstrap/template/", "encoding": "utf8", "destination": "./docs/", "recurse": true, "verbose": true }, "templates": { "cleverLinks": false, "monospaceLinks": false, "logoFile": "../assets/logo.png", "systemName": "开发文档", "navType": "inline", "theme": "united", //可取值: cosmo, cyborg, flatly, journal, lumen, paper,readable //sandstone, simplex, slate, spacelab, superhero, united, yeti "linenums": true },

其效果图如下所示：

也可以在生成的文件夹中直接改样式  docs > styles > 对应的css文件。

 4，Home页面

Home可以用markdown语法在README.md中生成，然后在package.json中添加调试命令如下：

 "scripts": { "docs": "jsdoc -c jsdoc.json README.md" },

此时通过 npm run docs 即可生成文档了

npm run docs

5，README.md

# 快速入门 概要 一，获取安装引用 1.1、获取安装<br/> 点击[【API文件下载】](https://www.baidu.com/?tn=_16_oem_dg)，获取file.js文件。如果是本地文件，这里的地址是相对项目中 docs 文件夹的地址 1.2、引用API方式<br/> 使用HTML方式引用， ``` <script src="目录/lib/baidu.js"></script> ``` 使用ES方式引用，在你使用组件的页面中，在最开始的js代码区域填写，代码示例如下： ``` <script> import { baidu} from '目录/lib/baidu.js' </script> ``` 加载场景成功后的效果图如下： ![效果图](../img/index.png)如果为本地图片，这里的地址是相对项目中 docs 文件夹的地址 Customize configuration See [Configuration Reference](https://www.baidu.com). 

总结

如果你还是没有头绪，可以参考下面的链接从头开始写，写完大概就懂了搭建jsdoc+ink-docstrap开发文档详细过程-CSDN博客