@agds/cli-plugin-doc

版本：1.0.16

agds系统doc文档生成器

快速开始

安装

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`	获取用来渲染模板的数据

RenderOptions : `object`

渲染函数的配置参数

性质: render的类型声明

属性

属性	类型	默认值	描述
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]	`JsdocEngineOptions`		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再次处理的钩子具体👉参考文档

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-markdownJsdocOptions` | `module:jsdoc-to-markdownRenderOptions` | `DataModifySupport`

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

性质: render的类型声明

DataModifySupport : `object`

在原有Jsdoc2mdOptions基础上扩展dataModify属性，支持修改templateData

性质: render的类型声明

属性

属性	类型
dataModify	`DataModify`

DataModify ⇒ `Array.<object>`

性质: render的类型声明

参数	类型
doclets	`Array.<object>`

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.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.map((doclet) => {
            if (doclet.alias) {
                doclet.id = doclet.memberof + '_alias_' + doclet.alias;
            }
            return doclet;
        }),
    },
    // 默认`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/cli-plugin-doc

@agds/cli-plugin-doc

快速开始

安装

命令行使用文档

配置文件

代码演示

API文档

GenDoc

引入

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

RenderOptions : object

DefaultHelpers : Object

Badge : Object

Postfix : Object

JsdocEngineOptions : Object

GetFilesCodeOptions : object

Jsdoc2mdOptions : module:jsdoc-to-markdownJsdocOptions | module:jsdoc-to-markdownRenderOptions | DataModifySupport

DataModifySupport : object

DataModify ⇒ Array.<object>

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

GetRenderDataResult : object

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

GetFilesCodeResult : Object.<string, string>

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

GenDoc.getFileContent(filename) ⇒ string

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

默认文档渲染模板

默认文档渲染配置

许可证

请维护者喝杯咖啡

加入钉钉群讨论或加入开发

Readme

Keywords

Package Sidebar

Install

Repository

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

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

RenderOptions : `object`

DefaultHelpers : `Object`

Badge : `Object`

Postfix : `Object`

JsdocEngineOptions : `Object`

GetFilesCodeOptions : `object`

Jsdoc2mdOptions : `module:jsdoc-to-markdownJsdocOptions` | `module:jsdoc-to-markdownRenderOptions` | `DataModifySupport`

DataModifySupport : `object`

DataModify ⇒ `Array.<object>`

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

GetRenderDataResult : `object`

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

GetFilesCodeResult : `Object.<string, string>`

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

GenDoc.getFileContent(filename) ⇒ `string`

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

Weekly Downloads