@agds/cli-plugin-doc v1.0.16
@agds/cli-plugin-doc
版本 :1.0.17
agds系统doc文档生成器
快速开始
安装
npm i -D @agds/cli-plugin-doc
命令行使用文档
Usage: agds-doc [options] [files...]
agds系统doc文档生成器
Arguments:
files jsdoc入口文件glob格式路径描述(需要用引号包裹避免解析失败),相对于cwd目录
Options:
-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.16 /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、👉默认模板
简单配置文件示例
// agds.doc.config.js
const GenDoc = require('@agds/cli-plugin-doc');
// 对象类型
module.exports = GenDoc.configDeclare({
files: ['src/index.js'],
output: 'README.md',
});
// 异步函数
module.exports = GenDoc.configDeclare(async () => {
const [template, cliUsages] = (await Promise.all([
GenDoc.getFilesCode({ dir: './src/template', files: ['*'] }),
GenDoc.getCliUsages(),
]));
return {
files: ['src/index.js'],
output: 'README.md',
helpers: {
postfixes: [
{
id: 'defaultTemplate',
title: '默认文档渲染模板',
content: GenDoc.renderCode(template),
},
],
cliUsages,
},
};
});
代码演示
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 = ({ needDirError, noFiles, noDefault, noCodes } = {}) => {
return GenDoc.configDeclare(
async () => {
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 | 获取用来渲染模板的数据 |
RenderOptions : object
渲染函数的配置参数
性质: render的类型声明
属性
属性 | 类型 | 默认值 | 描述 |
---|---|---|---|
files | Array.<string> | jsdoc2mdOptions.files 的别名 | |
output | module:fs-extra~PathLike | doc文档渲染导出的文件名称路径,相对于cwd目录 | |
template | string | ejs渲染的模板相对于cwd的路径或者绝对路径 | |
codesDir | string | codesOptions.dir 的别名 | |
codesFiles | Array.<string> | codesOptions.codesFiles 的别名 | |
conifg | module:fs-extra~PathLike | agds.doc.config.js | 配置文件路径,默认为运行目录下的agds.doc.config.js ,仅支持js 文件类型 |
default | boolean | 是否合并默认配置,一般我们认为您是需要默认配置的,当默认配置和你的需求冲突时可以设置为false | |
jsdoc2mdOptions | Jsdoc2mdOptions | jsdocToMarkdown配置参数 | |
codesOptions | GetFilesCodeOptions | 获取源代码的文件路径配置参数 | |
jsdocEngineOptions | JsdocEngineOptions | jsdoc解析引擎的配置,实际上是jsdoc.conf.js 的整合, 也可以使用 RenderOptions.jsdoc2mdOptions.configure 字段来指定本地的jsdoc配置 配置选项👉参考文档 | |
helpers | DefaultHelpers | 注入ejs模板的helpers 对象,提供模板使用的帮助函数和变量,配合模板使用 | |
presets | Array.<RenderOptions> | 基于preset机制实现配置支持预设的功能, 具体👉参考文档PresetUtils.getDeepPresetMerge | |
modify | module:@agds/node-utils/lib/types/utils/PresetUtils~ConfigModify | 将默认配置和preset合并后生成的config再次处理的钩子 具体👉参考文档 |
DefaultHelpers : Object
默认模板所支持的helpers
属性
性质: render的类型声明
属性
属性 | 类型 | 描述 |
---|---|---|
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
徽标对象
性质: render的类型声明
属性
属性 | 类型 | 描述 |
---|---|---|
url | string | 图片链接 |
name | string | 图片名称 |
link | string | 跳转链接 |
Postfix : Object
后缀内容类型
性质: render的类型声明
属性
属性 | 类型 | 描述 |
---|---|---|
id | string | 锚点的名称,填写之后可以支持 href="#${id}" 锚点定位 |
title | string | 内容的标题 |
desc | string | 内容的描述 |
content | string | 内容的正文 |
JsdocEngineOptions : Object
jsdoc引擎配置👉参考文档
性质: render的类型声明
属性
属性 | 类型 | 默认值 | 描述 |
---|---|---|---|
plugins | Array.<string> | 插件路径数组(建议使用绝对路径) | |
recurseDepth | number | 指定递归深度 | |
source | object | 指定输入文件 | |
source.include | Array.<string> | 路径数组,包含 JSDoc 应为其生成文档的文件 | |
source.exclude | Array.<string> | JSDoc 应该忽略的可选路径数组 | |
source.includePattern | string | 可选字符串,解释为正则表达式,如果存在,则所有文件名都必须与此正则表达式匹配才能由 JSDoc 处理 | |
source.excludePattern | string | 可选字符串,解释为正则表达式。如果存在,任何匹配此正则表达式的文件都将被忽略。 | |
sourceType | 'module' | 'script' | 'module' | 指定源类型,会影响 JSDoc 解析 JavaScript 文件的方式 |
tags | object | 配置标签和标签字典,tags控制允许使用哪些 JSDoc 标签以及如何解释每个标签的选项。 | |
tags.allowUnknownTags | boolean | Array.<string> | true | 影响 JSDoc 处理无法识别的标签的方式 |
tags.dictionaries | Array.<string> | "jsdoc","closure" | 控制 JSDoc 识别哪些标签,以及 JSDoc 如何解释它识别的标签。 |
GetFilesCodeOptions : object
获取源代码的文件路径配置参数
性质: render的类型声明
属性
属性 | 类型 | 描述 |
---|---|---|
dir | string | glob路径 |
files | Array.<string> | glob文件名称数组 |
Jsdoc2mdOptions : module:jsdoc-to-markdown~JsdocOptions | module:jsdoc-to-markdown~RenderOptions | DataModifySupport
jsdocToMarkdown配置参数,具体可👉参考文档
性质: render的类型声明
DataModifySupport : object
在原有Jsdoc2mdOptions基础上扩展dataModify属性,支持修改templateData
性质: render的类型声明
属性
属性 | 类型 | 描述 |
---|---|---|
dataModify | DataModify | 处理jsdoc Doclet对象数组的函数 |
DataModify ⇒ Array.<Doclet>
性质: render的类型声明
参数 | 类型 |
---|---|
doclets | Array.<Doclet> |
Doclet : object
jsdoc Doclet对象
性质: render的类型声明
属性
属性 | 类型 |
---|---|
id | string |
longname | string |
name | string |
kind | string |
description | string |
order | number |
meta | object |
meta.lineno | number |
meta.filename | string |
meta.path | string |
GenDoc.getRenderData(options, needMergeConfig) ⇒ Promise.<GetRenderDataResult>
获取用来渲染模板的数据(jsdoc生成的文档和示例代码的内容)
性质: GenDoc的静态方法
参数 | 类型 | 默认值 | 描述 |
---|---|---|---|
options | RenderOptions | 配置参数 | |
needMergeConfig | boolean | true | 是否需要调用_mergeToDefaultConfig , options已经是merge处理过的就不需要调用,否则不推荐传入false 会导致别名不支持 |
GetRenderDataResult : object
函数GenDoc.getRenderData的返回值
性质: getRenderData的类型声明
属性
属性 | 类型 | 描述 |
---|---|---|
docs | string | 源码使用jsdoc渲染后的markdown文本 |
codes | Array.<GetFilesCodeResult> | 获取到的代码内容 |
GenDoc.getFilesCode(options) ⇒ Promise.<Array.<GetFilesCodeResult>>
基于glob的文件遍历函数,返回文件对应内容的数组, 以文件夹为单位返回文件内容对象,key是文件的extname
性质: GenDoc的静态方法
参数 | 类型 | 描述 |
---|---|---|
options | GetFilesCodeOptions | 获取源代码的文件路径配置参数 |
GetFilesCodeResult : Object.<string, string>
获取文件的内容的返回值类型,key是文件的extname
性质: getFilesCode的类型声明
GenDoc.getCliUsages() ⇒ Promise.<Array.<string>>
获取命令行使用帮助文档 建议提前确保全局使用了最新的脚本 函数为异步函数,注意不能作为ejs帮助函数传入,可以获取返回值后,将返回值作为helpers的变量传入
性质: GenDoc的静态方法
GenDoc.getFileContent(filename) ⇒ string
读取文件内容
性质: GenDoc的静态方法
参数 | 类型 | 描述 |
---|---|---|
filename | string | 相对于运行目录的文件路径 |
GenDoc.configDeclare(config) ⇒ RenderOptions
辅助编写配置文件,优化类型显示
性质: GenDoc的静态方法
参数 | 类型 | 描述 |
---|---|---|
config | RenderOptions | RenderOptionsFn | 配置 |
RenderOptionsFn ⇒ RenderOptions | Promise.<RenderOptions>
性质: configDeclare的类型声明
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'} |
默认文档渲染模板
<%
const {docs, codes, helpers, pkg} = locals
%><% if(helpers.logo) { %><p align="center">
<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,
// 使用`@alias`标签时优化id的显示,以确保id的唯一性
dataModify: (doclets) => doclets.forEach((doclet) => {
if (doclet.alias && doclet.memberof) {
/* istanbul ignore next */
const accessSymbol = (doclet.scope === 'static' || doclet.scope === 'instance') ? '.' : doclet.scope === 'inner' ? '~' : '';
doclet.id = doclet.memberof + accessSymbol + doclet.name;
}
}),
},
// 默认`jsdocEngineOptions`配置一般只能增加无法删除,
// 但是可以在配置noDefault来去除默认配置
jsdocEngineOptions: {
plugins: [
require.resolve('jsdoc-tsimport-plugin'),
require.resolve('./jsdoc-plugin-arrowfn'),
require.resolve('jsdoc-typeof-plugin'),
],
},
helpers: {
renderCode,
},
};
module.exports = defaultConfig;
许可证
MIT License Copyright (c) 2021 锦阳