I’ve written a JSDoc-based document generator that supports powerful configurations to build your Markdown documents the same way WebPack builds WebApps

Because this tool is a tool I prepared to develop a development pipeline, which was designed for engineering purposes at the beginning of the design, the config file supports the introduction of preset, which makes it easy to maintain uniform configuration in the team

Resources:

There are problems with markdow hash redirect support. If you want to jump through hyperlinks, you can go to the warehouse page to view the documents
NPM address
Warehouse group address, you can find some simple sample applications in this group project, easy to understand
Description of configuration file type definitions

Below is its own document generated by the document generator, which should be easy for those familiar with jSDoc-to-Markdown to understand

Unfortunately, MY narrative ability is not strong, can only directly dump the document 😭

@agds/cli-plugin-doc

Version: 1.0.14

General comments to Markdown document generator, which aims to support all types of files

Quick start

The installation

npm i -D @agds/cli-plugin-doc
Copy the code

Command line use documentation

Usage: AGDS-doc [options] AGDS system doc Document generator options: <files... > jsdoc entry file glob format path description (need to be enclosed in quotes to avoid parsing failure), relative to CWD directory -o,--output <output> doc document render export file name path, Relative to the CWD directory -c,--config <config> Configuration file path. Relative to the CWD directory, only the JS file type is supported. (default: "Agds.doc.config. js") -t,--template <template> EjS render template relative to CWD path or absolute path -- CD,--codes-dir <codesDir> glob format path, The path to the corresponding folder of a specific example --cf,--codes-files <codesFiles... > glob format path, relative to codesDir code demo folder file path description --no-default Disallow default configuration, default configuration is relatively common, most cases do not need to disable, -v,--version Check the version number -h, --help Check the help information Note: Each path containing wildcards must be enclosed in quotation marks, otherwise it will be parsed in advance, resulting in unexpected errors. https://gitee.com/agile-development-system/cli-plugin-doc @ agds/[email protected] /Users/jinyang/code/ads/cli-plugin-doc/node_modules/@agds/cli-plugin-docCopy the code

The configuration file

The default is agds.doc.config.js in the current directory. The default configuration is automatically merged

You can specify the configuration file name using either the -c –config

command line argument or the Options. config of the Node API

You can use the –no-default command line argument or the Options. default=false of the Node API to disable the default configuration. The default configuration is relatively common and you do not need to disable it in most cases

The export type of the configuration file is 👉RenderOptions, which supports all RenderOptions. For details about helpers provided by the default template, see 👉 and 👉

Code demo


const GenDoc = require('@agds/cli-plugin-doc');
/** * render render@param {object} [options = {}] options *@param {boolean} [options.needDirError] Whether file path errors need to be triggered *@param {boolean} [options.noFiles] Whether to remove the files option *@param {boolean} [options.noDefault] Whether to cancel the default configuration *@param {boolean} [options.noCodes] Whether to remove cods-related configuration *@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: [The '*'] }),
        GenDoc.getFilesCode({ dir: './src/utils'.files: ['config.js'] }),
        GenDoc.getCliUsages(),
    ]));
    return {
        files: noFiles ? null : ['./src/**/*.js'],... (noCodes ? {}, {codesDir: needDirError ? './aaa' : './exa'.codesFiles: [The '*'],}).config: './agds.doc.conf.js'.default: !noDefault,
        jsdocEngineOptions: noDefault && {
            plugins: [
                require.resolve('jsdoc-tsimport-plugin')]},helpers: {
            template,
            defaultConfig,
            cliUsages,
        },
    };
};
Copy the code

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('No directory was matched, please confirm input path'); }}); 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);
});
Copy the code

The API documentation

GenDoc

GenDoc’s powerful utility classes automatically generate documentation based on annotations and runnable sample code

The introduction of

const GenDoc = require('@agds/cli-plugin-doc');
Copy the code

Properties: class

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

Based on EJS, render documents with templates

Property: GenDoc static method return value: Promise.

– Asynchronously returns document text rendered based on EJS templates

parameter	type	describe
options	`RenderOptions`	Gets the data used to render the template

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

Get the data used to render the template (contents of jsDoc generated documentation and sample code)