jsDoc开发文档生成

Weslie_zt

已于 2024-05-13 14:29:02 修改

阅读量375

点赞数 7

文章标签：前端开发语言

于 2024-05-13 11:25:36 首次发布

本文链接：https://blog.csdn.net/pleasantsheep_/article/details/138785248

版权

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

前言

提示：在使用前确定你的电脑已安装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=62095104_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).