@agds/cli-plugin-doc/lib/types/index.d.ts

agds系统doc文档生成器

export = GenDoc;
/**
 * GenDoc 基于注释和可运行的示例代码自动生成文档的强大工具类
 *
 * #### 引入
 *
 * ```js
 * const GenDoc = require('@agds/cli-plugin-doc');
 * ```
 */
declare class GenDoc {
    /**
     * 基于ejs，用模板渲染文档
     *
     * @param {RenderOptions} options 获取用来渲染模板的数据
     * @returns {Promise<string>} 异步返回基于ejs模板渲染的文档文本
     */
    static render(options: RenderOptions): Promise<string>;
    /**
     * 获取用来渲染模板的数据（jsdoc生成的文档和示例代码的内容）
     *
     * @param {RenderOptions} options 配置参数
     * @param {boolean} [needMergeConfig=true] 是否需要调用`_mergeToDefaultConfig`，
     * options已经是merge处理过的就不需要调用,否则不推荐传入`false`
     * 会导致别名不支持
     * @returns {Promise<GetRenderDataResult>}
     */
    static getRenderData(options: RenderOptions, needMergeConfig?: boolean): Promise<GetRenderDataResult>;
    /**
     * 基于glob的文件遍历函数，返回文件对应内容的数组，
     * 以文件夹为单位返回文件内容对象，key是文件的extname
     *
     * @param {import('./utils/getFilesPath').GetFilesCodeOptions} options 获取源代码的文件路径配置参数
     * @returns {Promise<Array<import('./utils/renderCode').GetFilesCodeResult>>}
     */
    static getFilesCode(options: import('./utils/getFilesPath').GetFilesCodeOptions): Promise<Array<import('./utils/renderCode').GetFilesCodeResult>>;
    static renderCode: typeof renderCode;
    /**
     * 获取命令行使用帮助文档
     * 建议提前确保全局使用了最新的脚本
     * 函数为异步函数，注意不能作为ejs帮助函数传入，可以获取返回值后，将返回值作为helpers的变量传入
     *
     * @returns {Promise<string[]>}
     */
    static getCliUsages(): Promise<string[]>;
    /**
     * 读取文件内容
     *
     * @param {string} filename 相对于运行目录的文件路径
     * @returns {string}
     */
    static getFileContent(filename: string): string;
}
declare namespace GenDoc {
    export { GetRenderDataResult, RenderOptions, DefaultHelpers, Badge, Postfix, JsdocEngineOptions };
}
/**
 * 渲染函数的配置参数
 */
type RenderOptions = {
    /**
     * `jsdoc2mdOptions.files`的别名
     */
    files: string[];
    /**
     * doc文档渲染导出的文件名称路径，相对于cwd目录
     */
    output: fs.PathLike;
    /**
     * ejs渲染的模板相对于cwd的路径或者绝对路径
     */
    template: string;
    /**
     * `codesOptions.dir`的别名
     */
    codesDir?: string;
    /**
     * `codesOptions.codesFiles`的别名
     */
    codesFiles?: string[];
    /**
     * 配置文件路径，默认为运行目录下的`agds.doc.config.js`,仅支持`js`文件类型
     */
    conifg?: fs.PathLike;
    /**
     * 是否合并默认配置，一般我们认为您是需要默认配置的，当默认配置和你的需求冲突时可以设置为`false`
     */
    default?: boolean;
    /**
     * jsdocToMarkdown配置参数
     */
    jsdoc2mdOptions?: import('./utils/jsdocRender').Jsdoc2mdOptions;
    /**
     * 获取源代码的文件路径配置参数
     */
    codesOptions?: import('./utils/getFilesPath').GetFilesCodeOptions;
    /**
     * jsdoc解析引擎的配置，实际上是`jsdoc.conf.js`的整合，
     * 也可以使用  `RenderOptions.jsdoc2mdOptions.configure`字段来指定本地的jsdoc配置
     * 配置选项[👉参考文档](https://jsdoc.app/about-configuring-jsdoc.html)
     */
    jsdocEngineOptions?: JsdocEngineOptions;
    /**
     * 注入ejs模板的`helpers`对象，提供模板使用的帮助函数和变量，配合模板使用
     */
    helpers?: DefaultHelpers;
    /**
     * 基于preset机制实现配置支持预设的功能，
     * 具体[👉参考文档](https://gitee.com/agile-development-system/node-utils#presetutilsgetdeeppresetmergeconfig--config)`PresetUtils.getDeepPresetMerge`
     */
    presets?: RenderOptions[];
    /**
     * 将默认配置和preset合并后生成的config再次处理的钩子
     * 具体[👉参考文档](https://gitee.com/agile-development-system/node-utils#presetutilsgetdeeppresetmergeconfig--config)
     */
    modify?: any;
};
/**
 * 函数[GenDoc.getRenderData](#GenDoc.getRenderData)的返回值
 */
type GetRenderDataResult = {
    /**
     * 源码使用jsdoc渲染后的markdown文本
     */
    docs: string;
    /**
     * 获取到的代码内容
     */
    codes: Array<import('./utils/renderCode').GetFilesCodeResult>;
};
import renderCode = require("./utils/renderCode");
/**
 * 默认模板所支持的`helpers`属性
 */
type DefaultHelpers = {
    /**
     * 安装脚本，bash脚本，默认为`npm i ${pkg.name}`，如不符合要求，可以通过此字段自行修改
     */
    installCode?: string;
    /**
     * 是否是作为开发依赖下载，`true`时，默认下载代码自动拼接npm `-D` 参数
     */
    devInstall?: boolean;
    /**
     * 引入代码示例，js字符串
     */
    importCode?: string;
    /**
     * 导出代码，js字符串
     */
    exportCode?: string;
    /**
     * cli命令行使用帮助文档，格式类似`agds-doc -h`的输出内容
     */
    cliUsages?: string[];
    /**
     * 文档备注信息，md字符串
     */
    remark?: string;
    /**
     * 将`GenDoc.getFileCodes`的返回值渲染成对应的代码段
     */
    renderCode?: typeof renderCode;
    /**
     * 后缀内容数组
     */
    postfixes?: Postfix[];
    /**
     * logo
     */
    logo?: string;
    /**
     * 徽标数组
     */
    bradges?: Badge[];
};
/**
 * 徽标对象
 */
type Badge = {
    /**
     * 图片链接
     */
    url: string;
    /**
     * 图片名称
     */
    name?: string;
    /**
     * 跳转链接
     */
    link?: string;
};
/**
 * 后缀内容类型
 */
type Postfix = {
    /**
     * 锚点的名称，填写之后可以支持 `href="#${id}"`锚点定位
     */
    id?: string;
    /**
     * 内容的标题
     */
    title?: string;
    /**
     * 内容的描述
     */
    desc?: string;
    /**
     * 内容的正文
     */
    content?: string;
};
/**
 * jsdoc引擎配置[👉参考文档](https://jsdoc.app/about-configuring-jsdoc.html)
 */
type JsdocEngineOptions = {
    /**
     * 插件路径数组(建议使用绝对路径)
     */
    plugins: string[];
    /**
     * 指定递归深度
     */
    recurseDepth: number;
    /**
     * 指定输入文件
     */
    source: {
        include: string[];
        exclude: string[];
        includePattern: string;
        excludePattern: string;
    };
    /**
     * 指定源类型,会影响 JSDoc 解析 JavaScript 文件的方式
     */
    sourceType?: 'module' | 'script';
    /**
     * 配置标签和标签字典,tags控制允许使用哪些 JSDoc 标签以及如何解释每个标签的选项。
     */
    tags: {
        allowUnknownTags?: boolean | string[];
        dictionaries?: string[];
    };
};
import fs = require("fs-extra");