10-13 01:31 阅读 360

强大的基于jsdoc的markdown文档生成器

我编写了一个基于jsdoc的文档生成器，支持强大的配置，像webpack构建webapp一样构建你的markdown文档

因为这个工具是我准备开发一个开发流水线而准备的工具，在设计之初就是为了工程化而准备的，所以config文件支持引入预设，在团队中，可以很轻易的维护统一的配置

资源目录：

项目地址，掘金文章对markdow哈希跳转支持有问题，想要通过超链接进行跳转的话可以去仓库页面查看文档
npm地址
仓库组地址，可以在这个组的项目里面找到一些简单的示例应用，方便理解
配置文件类型定义说明

下面是通过这个文档生成器生成的它自己的文档，熟悉jsdoc-to-markdown的同学应该可以很容易的了解这个工具的用法

可惜我叙述能力不强，只能直接甩文档了????

logo

@agds/cli-plugin-doc

版本：1.0.14

通用注释转markdown文档生成器,目标是支持所有类型的文件

快速开始

安装

npm i -D @agds/cli-plugin-doc 复制代码

命令行使用文档

Usage: agds-doc [options] agds系统doc文档生成器 Options:   <files...>                          jsdoc入口文件glob格式路径描述(需要用引号包裹避免解析失败)，相对于cwd目录   -o,--output <output>                doc文档渲染导出的文件名称路径，相对于cwd目录   -c,--config <config>                配置文件路径，相对于cwd目录，仅支持js文件类型 (default:                                       "agds.doc.config.js")   -t,--template <template>            ejs渲染的模板相对于cwd的路径或者绝对路径   --cd,--codes-dir <codesDir>         glob格式路径，代码演示示例的对应文件夹路径，路径需要到某个具体示例的对应文件夹   --cf,--codes-files <codesFiles...>  glob格式路径，相对于codesDir的代码演示文件夹的文件路径描述   --no-default                        禁止使用默认配置，默认配置相对比较通用，大部分情况不需要禁止，当默认配置和你的配置冲突时可以使用此选项   -v,--version                        查看版本号   -h, --help                          查看帮助信息 注意：每个包含通配符的路径都需要用引号包裹，否则会被系统提前解析导致意料之外的错误 文档查看：https://gitee.com/agile-development-system/cli-plugin-doc @agds/cli-plugin-doc@1.0.12 /Users/jinyang/code/ads/cli-plugin-doc/node_modules/@agds/cli-plugin-doc 复制代码

配置文件

默认为当前目录下的agds.doc.config.js，自动合并默认配置

可以通过命令行参数-c --config <config>或者node api的options.config 来指定配置文件名称

可以通过命令行参数--no-default或者node api的options.default=false 来禁止使用默认配置，默认配置相对比较通用，大部分情况不需要禁止，当默认配置和你的配置冲突时可以使用此选项

配置文件导出类型为????RenderOptions,理论上支持所有的renderOption，由默认模板提供的helpers配置请看????默认模板支持的helpers、????默认模板

代码演示

 const GenDoc = require('@agds/cli-plugin-doc'); /**  * render配置生成  *  * @param {object} [options={}] 选项  * @param {boolean} [options.needDirError] 是否需要触发文件路径错误  * @param {boolean} [options.noFiles] 是否需要去除files选项  * @param {boolean} [options.noDefault] 是否取消default配置  * @param {boolean} [options.noCodes] 是否去除codes相关配置  * @returns {import('../../src/index').RenderOptions}  */ module.exports = async ({ needDirError, noFiles, noDefault, noCodes } = {}) => {     const [template, defaultConfig, cliUsages] = (await Promise.all([         GenDoc.getFilesCode({ dir: './src/template', files: ['*'] }),         GenDoc.getFilesCode({ dir: './src/utils', files: ['config.js'] }),         GenDoc.getCliUsages(),     ]));     return {         files: noFiles ? null : ['./src/**/*.js'],         ...(noCodes             ? {}             : {                 codesDir: needDirError ? './aaa' : './exa',                 codesFiles: ['*'],             }         ),         config: './agds.doc.conf.js',         default: !noDefault,         jsdocEngineOptions: noDefault && {             plugins: [                 require.resolve('jsdoc-tsimport-plugin'),             ],         },         helpers: {             template,             defaultConfig,             cliUsages,         },     }; }; 复制代码

const { expect, test } = require('@jest/globals'); const GenDoc = require('@agds/cli-plugin-doc'); const config = require('../__mock__/index'); const path = require('path'); test('GenDoc render', async () => {     const res = await GenDoc.render(await config());     expect(typeof res === 'string').toBe(true); }); test('GenDoc render output & use agds.doc.config.js', async () => {     const res = await GenDoc.render({         output: path.resolve(__dirname, '../../.temp/README.md'),     });     expect(typeof res === 'undefined').toBe(true); }); test('GenDoc render no files', async () => {     const res = await GenDoc.render(await config({ noFiles: true }));     expect(typeof res === 'string').toBe(true); }); test('GenDoc render no codes', async () => {     const res = await GenDoc.render(await config({ noCodes: true }));     expect(typeof res === 'string').toBe(true); }); test('GenDoc render error', async () => {     try {         await GenDoc.render(await config({ needDirError: true }));     } catch (error) {         expect(error.message).toMatch('未匹配到任何目录，请确认输入路径');     } }); test('GenDoc getRenderData nodefault', async () => {     const res = await GenDoc.getRenderData(await config({ noDefault: true }));     expect(typeof res === 'object').toBe(true); }); test('GenDoc getRenderData', async () => {     const res = await GenDoc.getRenderData(await config(), false);     expect(typeof res === 'object').toBe(true); }); test('GenDoc getFileContent', () => {     const res = GenDoc.getFileContent('./README.md');     expect(typeof res === 'string').toBe(true); }); 复制代码

API文档

GenDoc

GenDoc 基于注释和可运行的示例代码自动生成文档的强大工具类

引入

const GenDoc = require('@agds/cli-plugin-doc'); 复制代码

性质: 类

GenDoc.render(options) ⇒ `Promise.<string>`

基于ejs，用模板渲染文档

性质: GenDoc的静态方法 返回值: Promise.<string> - 异步返回基于ejs模板渲染的文档文本

参数	类型	描述
options	`RenderOptions`	获取用来渲染模板的数据

GenDoc.getRenderData(options, [needMergeConfig]) ⇒ `Promise.<GetRenderDataResult>`

获取用来渲染模板的数据（jsdoc生成的文档和示例代码的内容）

性质: GenDoc的静态方法

参数	类型	默认值	描述
options	`RenderOptions`		配置参数
[needMergeConfig]	`boolean`	`true`	是否需要调用`_mergeToDefaultConfig`， options已经是merge处理过的就不需要调用,否则不推荐传入`false` 会导致别名不支持

GenDoc.getFilesCode(options) ⇒ `Promise.<Array.<GetFilesCodeResult>>`

基于glob的文件遍历函数，返回文件对应内容的数组，以文件夹为单位返回文件内容对象，key是文件的extname

性质: GenDoc的静态方法

参数	类型	描述
options	`GetFilesCodeOptions`	获取源代码的文件路径配置参数

GenDoc.getCliUsages() ⇒ `Promise.<Array.<string>>`

获取命令行使用帮助文档建议提前确保全局使用了最新的脚本函数为异步函数，注意不能作为ejs帮助函数传入，可以获取返回值后，将返回值作为helpers的变量传入

性质: GenDoc的静态方法

GenDoc.getFileContent(filename) ⇒ `string`

读取文件内容

性质: GenDoc的静态方法

参数	类型	描述
filename	`string`	相对于运行目录的文件路径

GenDoc.renderCode(codes, [extSort], [extTrans]) ⇒ `string`

将codes渲染成md代码片段

性质: GenDoc的静态方法

参数	类型	默认值	描述
codes	`Array.<GetFilesCodeResult>`		`GenDoc.getFilesCode`函数获取到的codes数组
[extSort]	`Array.<string>`	`['md', 'vue', 'jsx', 'js']`	优先并且按照`extSort`数组顺序获取遍历codes
[extTrans]	`Object.<string, string>`	`{vue:'html'}`	ext转换的映射map 简单示例`{vue:'html'}`

GetRenderDataResult : `object`

函数GenDoc.getRenderData的返回值

性质: 类型声明

属性

属性	类型	描述
docs	`string`	源码使用jsdoc渲染后的markdown文本
codes	`Array.<GetFilesCodeResult>`	获取到的代码内容

RenderOptions : `object`

渲染函数的配置参数

性质: 类型声明

属性

属性	类型	默认值	描述
files	`Array.<string>`		`jsdoc2mdOptions.files`的别名
output	`fs.PathLike`		doc文档渲染导出的文件名称路径，相对于cwd目录
template	`string`		ejs渲染的模板相对于cwd的路径或者绝对路径
[codesDir]	`string`		`codesOptions.dir`的别名
[codesFiles]	`Array.<string>`		`codesOptions.codesFiles`的别名
[conifg]	`fs.PathLike`	`agds.doc.config.js`	配置文件路径，默认为运行目录下的`agds.doc.config.js`,仅支持`js`文件类型
[default]	`boolean`		是否合并默认配置，一般我们认为您是需要默认配置的，当默认配置和你的需求冲突时可以设置为`false`
[jsdoc2mdOptions]	`Jsdoc2mdOptions`		jsdocToMarkdown配置参数
[codesOptions]	`GetFilesCodeOptions`		获取源代码的文件路径配置参数
[jsdocEngineOptions]	`object`		jsdoc解析引擎的配置，实际上是`jsdoc.conf.js`的整合，也可以使用 `RenderOptions.jsdoc2mdOptions.configure`字段来指定本地的jsdoc配置配置选项????参考文档
[helpers]	`DefaultHelpers`		注入ejs模板的`helpers`对象，提供模板使用的帮助函数和变量，配合模板使用
[presets]	`Array.<RenderOptions>`		基于preset机制实现配置支持预设的功能，具体????参考文档`PresetUtils.getDeepPresetMerge`
[modify]	`module:@agds/node-utils~ConfigModify`		将默认配置和preset合并后生成的config再次处理的钩子具体????参考文档

GetFilesCodeResult : `Object.<string, string>`

获取文件的内容的返回值类型，key是文件的extname

性质: 类型声明

DefaultHelpers : `Object`

默认模板所支持的helpers属性

性质: 类型声明

属性

属性	类型	描述
[installCode]	`string`	安装脚本，bash脚本，默认为`npm i ${pkg.name}`，如不符合要求，可以通过此字段自行修改
[devInstall]	`boolean`	是否是作为开发依赖下载，`true`时，默认下载代码自动拼接npm `-D` 参数
[importCode]	`string`	引入代码示例，js字符串
[exportCode]	`string`	导出代码，js字符串
[cliUsages]	`Array.<string>`	cli命令行使用帮助文档，格式类似`agds-doc -h`的输出内容
[remark]	`string`	文档备注信息，md字符串
[renderCode]	`renderCode`	将`GenDoc.getFileCodes`的返回值渲染成对应的代码段
[postfixes]	`Array.<Postfix>`	后缀内容数组
[logo]	`string`	logo
[bradges]	`Array.<Badge>`	徽标数组

Badge : `Object`

徽标对象

性质: 类型声明

属性

属性	类型	描述
url	`string`	图片链接
[name]	`string`	图片名称
[link]	`string`	跳转链接

Postfix : `Object`

后缀内容类型

性质: 类型声明

属性

属性	类型	描述
[id]	`string`	锚点的名称，填写之后可以支持 `href="#${id}"`锚点定位
[title]	`string`	内容的标题
[desc]	`string`	内容的描述
[content]	`string`	内容的正文

GetFilesCodeOptions : `object`

获取源代码的文件路径配置参数

性质: 类型声明

属性

属性	类型	描述
dir	`string`	glob路径
files	`Array.<string>`	glob文件名称数组

Jsdoc2mdOptions : `object`

jsdocToMarkdown配置参数，具体可????参考文档

性质: 类型声明

默认文档渲染模板

<% const {docs, codes, helpers, pkg} = locals %><% if(helpers.logo) { %><p>     <img src="<%- helpers.logo %>" alt="logo"> </p> <% } if(pkg.name){ %># <%- pkg.name %><% } %><% if (helpers.badges && helpers.badges.length > 0) { %> <%- helpers.badges.map(item => {     let badge = `![${item.name}](${item.url})`;     if (item.link) {         badge = `[${badge}](${item.link})`;     }     return badge; }).join(' '); %><% } %><% if(pkg.version){ %> **版本** ：<%- pkg.version %><% } %><% if(pkg.description){ %> <%- pkg.description %><% } %><% if(pkg.name||helpers.importCode||helpers.exportCode) { %> ## 快速开始 <% } %><% if(pkg.name){ %> ### 安装 <%  %>```bash <%- helpers.installCode || 'npm i '+ (helpers.devInstall? '-D ' : '') + pkg.name %> <%  %>``` <% } %><% if(helpers.importCode) { %> ### 引入 <%  %>```js <%- helpers.importCode %> <%  %>``` <% } %><% if(helpers.exportCode) { %> ### 导出 <%  %>```js <%- helpers.exportCode %> <%  %>``` <% } %><% if(helpers.cliUsages&&helpers.cliUsages.length) { %> ### 命令行使用文档 <% helpers.cliUsages.forEach(usage=>{ %> <%  %>``` <%- usage %> <%  %>```<% }) %><% } %><% if(helpers.remark) { %> <%- helpers.remark %> <% } %><% if(codes&&codes.length) { %> ## 代码演示 <%-     helpers.renderCode         &&helpers.renderCode(codes) %><% } %><% if(docs) { %> ## API文档 <%- docs %><% } %><% if(helpers.postfixes&&helpers.postfixes.length) { // 后缀内容 %><% helpers.postfixes.forEach(postfix=>{ %> <% if(postfix.id) { %> <a name="<%- postfix.id %>"></a><% } %><% if(postfix.title) { %> ## <%- postfix.title %> <% } %><% if(postfix.desc) { %> > <%- postfix.desc %> <% } %><% if(postfix.content) { %> <%- postfix.content %><% } }) } %> 复制代码

默认文档渲染配置

当前__dirname为@agds/cli-plugin-doc/lib/utils

const path = require('path'); const defaultTemplate = path.resolve(__dirname, '../template/template.ejs'); const renderCode = require('./renderCode'); const defaultConfig = {     template: defaultTemplate,     jsdoc2mdOptions: {         // 'no-cache': true,         partial: [path.resolve(__dirname, '../dmdRewrite/partials/*.hbs')],         helper: [path.resolve(__dirname, '../dmdRewrite/helpers/*.js')],         'heading-depth': 3,     },     // 默认`jsdocEngineOptions`配置一般只能增加无法删除，     // 但是可以在配置noDefault来去除默认配置     jsdocEngineOptions: {         plugins: [             require.resolve('jsdoc-tsimport-plugin'),             require.resolve('./jsdoc-plugin-arrowfn'),             require.resolve('jsdoc-typeof-plugin'),         ],     },     helpers: {         renderCode,     }, }; module.exports = defaultConfig; 复制代码

许可证

作者：锦阳_AGDS
链接：https://juejin.cn/post/7018185196977684510

强大的基于jsdoc的markdown文档生成器

资源目录：

@agds/cli-plugin-doc

快速开始

安装

命令行使用文档

配置文件

代码演示

API文档

GenDoc

引入

GenDoc.render(options) ⇒ Promise.<string>

GenDoc.getRenderData(options, [needMergeConfig]) ⇒ Promise.<GetRenderDataResult>

GenDoc.getFilesCode(options) ⇒ Promise.<Array.<GetFilesCodeResult>>

GenDoc.getCliUsages() ⇒ Promise.<Array.<string>>

GenDoc.getFileContent(filename) ⇒ string

GenDoc.renderCode(codes, [extSort], [extTrans]) ⇒ string

GetRenderDataResult : object

RenderOptions : object

GetFilesCodeResult : Object.<string, string>

DefaultHelpers : Object

Badge : Object

Postfix : Object

GetFilesCodeOptions : object

Jsdoc2mdOptions : object

默认文档渲染模板

默认文档渲染配置

许可证

GenDoc.render(options) ⇒ `Promise.<string>`

GenDoc.getRenderData(options, [needMergeConfig]) ⇒ `Promise.<GetRenderDataResult>`

GenDoc.getFilesCode(options) ⇒ `Promise.<Array.<GetFilesCodeResult>>`

GenDoc.getCliUsages() ⇒ `Promise.<Array.<string>>`

GenDoc.getFileContent(filename) ⇒ `string`

GenDoc.renderCode(codes, [extSort], [extTrans]) ⇒ `string`

GetRenderDataResult : `object`

RenderOptions : `object`

GetFilesCodeResult : `Object.<string, string>`

DefaultHelpers : `Object`

Badge : `Object`

Postfix : `Object`

GetFilesCodeOptions : `object`

Jsdoc2mdOptions : `object`