vuepress-jsdoc 5.0.0 → 6.1.0

package/dist/index.js

@@ -1,18 +1,3 @@
-"use strict";
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.watchFiles = exports.generate = void 0;
 /*
  * @vuepress
  * ---
@@ -20,181 +5,244 @@ exports.watchFiles = exports.generate = void 0;
  * headline: The Main File
  * ---
  */
-const chokidar_1 = __importDefault(require("chokidar"));
-const del_1 = __importDefault(require("del"));
-const kleur_1 = __importDefault(require("kleur"));
-const mkdirp_1 = require("mkdirp");
-const promises_1 = __importDefault(require("node:fs/promises"));
-const node_readline_1 = __importDefault(require("node:readline"));
-const constants_1 = require("./constants");
-const list_folder_1 = require("./lib/list-folder");
-const parser_1 = require("./lib/parser");
-const vue_sidebar_1 = require("./lib/vue-sidebar");
+import chokidar from 'chokidar';
+import { deleteAsync } from 'del';
+import kleur from 'kleur';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { StatisticType } from './constants.js';
+import { getPageName, listFolder, normalizePath } from './lib/list-folder.js';
+import { getDestFolder, parseFile, writeContentToFile } from './lib/parser.js';
+import { createSidebarConfig } from './lib/vue-sidebar.js';
+export { listFolder } from './lib/list-folder.js';
+export { parseFile, writeContentToFile } from './lib/parser.js';
+export { createSidebarConfig, generateVitepressSidebar, generateVueSidebar } from './lib/vue-sidebar.js';
+export { parseComment, parseVuepressFileHeader } from './lib/comment-parser.js';
+export { defineConfig, loadConfig } from './lib/config.js';
+export { vuepressJsdocPlugin } from './lib/vuepress-plugin.js';
+export { StatisticType } from './constants.js';
 /**
- * Create the sidebar
- * @param {object} options
- * @returns {Promise}
+ * Split a comma separated string or a list of strings into a list
+ * @param {string|string[]} value
+ * @returns {string[]}
  */
-const createVuepressSidebar = (options) => promises_1.default.writeFile(`${options.docsFolder}/config.js`, `exports.fileTree=${JSON.stringify(options.fileTree)};exports.sidebarTree = (title = 'Mainpage') => (${JSON.stringify((0, vue_sidebar_1.generateVueSidebar)(options)).replace('::vuepress-jsdoc-title::', '"+title+"')});`);
+const toList = (value) => (Array.isArray(value) ? value : (value || '').split(','))
+    .flatMap((v) => v.split(','))
+    .map((v) => v.trim())
+    .filter(Boolean);
 /**
- * Parse file
- * @param {DirectoryFile} file
+ * Parse all CLI arguments
  * @param {CLIArguments} argv
- * @returns {Promise}
+ * @returns {object} all arguments
  */
-const parseDirectoryFile = (file, argv) => {
-    const { srcFolder, docsFolder, partials } = parseArguments(argv);
-    if (!file.isDir && file.folder) {
-        if (['.jsx', '.tsx', '.ts', '.js'].includes(file.ext || '')) {
-            return (0, parser_1.parseFile)(file, srcFolder, docsFolder, argv.jsDocConfigPath, partials);
-        }
-        if (file.ext === '.vue') {
-            return (0, parser_1.parseVueFile)(file, srcFolder, docsFolder);
+export const parseArguments = (argv) => {
+    const codeFolder = normalizePath(argv.folder || 'code');
+    const dist = normalizePath(argv.dist || './documentation');
+    const srcFolder = normalizePath(argv.source || './src');
+    return {
+        include: toList(argv.include),
+        exclude: toList(argv.exclude),
+        srcFolder,
+        codeFolder,
+        docsFolder: path.posix.join(dist, codeFolder),
+        title: argv.title || 'API',
+        readme: argv.readme,
+        readmePath: argv.readme || path.join(srcFolder, 'README.md'),
+        rmPattern: toList(argv.rmPattern),
+        partials: toList(argv.partials),
+        jsDocConfigPath: argv.jsDocConfigPath,
+        collapsible: Boolean(argv.collapsible),
+        format: argv.format === 'vitepress' ? 'vitepress' : 'vuepress'
+    };
+};
+/**
+ * Run async tasks with a limited concurrency, because every jsdoc call spawns a child process.
+ * @param {T[]} items
+ * @param {Function} fn
+ * @returns {Promise<R[]>} results in the order of the items
+ */
+const mapLimit = async (items, fn, limit = os.availableParallelism()) => {
+    const results = new Array(items.length);
+    let index = 0;
+    const worker = async () => {
+        while (index < items.length) {
+            const i = index++;
+            results[i] = await fn(items[i]);
         }
-    }
+    };
+    await Promise.all(Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, worker));
+    return results;
+};
+/**
+ * Get the sidebar options of the given file tree
+ * @param {Options} options
+ * @param {FileTree[]} fileTree created by `listFolder`
+ * @returns {SidebarOptions}
+ */
+export const getSidebarOptions = (options, fileTree) => ({
+    fileTree,
+    srcFolder: options.srcFolder,
+    docsFolder: options.docsFolder,
+    codeFolder: options.codeFolder,
+    title: options.title,
+    format: options.format,
+    collapsible: options.collapsible
+});
+/**
+ * Write the config.js with the file tree and sidebar
+ * @param {Options} options
+ * @param {FileTree[]} fileTree created by `listFolder`
+ * @returns {Promise<void>}
+ */
+const createVuepressSidebar = (options, fileTree) => fs.writeFile(path.join(options.docsFolder, 'config.js'), createSidebarConfig(getSidebarOptions(options, fileTree)));
+/**
+ * Parse a file and write the markdown file
+ * @param {DirectoryFile} file
+ * @param {Options} options
+ * @returns {Promise<ParseReturn>}
+ */
+const processFile = async (file, options) => {
+    const parseOptions = {
+        srcFolder: options.srcFolder,
+        destFolder: options.docsFolder,
+        jsDocConfigPath: options.jsDocConfigPath,
+        partials: options.partials
+    };
+    const result = await parseFile(file, parseOptions);
+    await writeContentToFile(result);
+    return result;
 };
 /**
  * Create the readme file. First page when entering the documentation.
- * @param {CLIArguments} argv
- * @param {string} deletedPaths
- * @returns {void}
+ * @param {Options} options
+ * @returns {Promise<void>}
  */
-const createReadmeFile = (argv, deletedPaths) => __awaiter(void 0, void 0, void 0, function* () {
-    const { srcFolder, codeFolder, docsFolder, title, readme } = parseArguments(argv);
-    let readMeContent = `### Welcome to ${title}`;
-    const readmePath = readme || `${srcFolder}/README.md`;
+const createReadmeFile = async (options) => {
+    const { readmePath } = options;
+    // vitepress uses index.md as the page of a folder
+    const target = options.format === 'vitepress' ? 'index.md' : 'README.md';
+    let content = `# ${options.title}\n`;
     try {
-        readMeContent = yield promises_1.default.readFile(readmePath, 'utf-8');
-        if (deletedPaths === null || deletedPaths === void 0 ? void 0 : deletedPaths.some((p) => p.indexOf(`${codeFolder}/README.md`) !== -1)) {
-            console.log(`\n${kleur_1.default.white().bgBlack(' README ')} ${kleur_1.default.dim(readmePath.replace('README.md', ''))}${kleur_1.default.bold('README.md')} \u2192  ${kleur_1.default.dim(docsFolder)}${kleur_1.default.bold('/README.md')}`);
-        }
+        content = await fs.readFile(readmePath, 'utf-8');
+        console.log(`${kleur.white().bgBlack(' README ')} ${kleur.dim(readmePath)} → ${kleur.dim(options.docsFolder)}/${target}`);
     }
-    catch (e) {
-        console.log(`\n${kleur_1.default.white().bgBlack(' README ')} Add default README.md`);
+    catch {
+        console.log(`${kleur.white().bgBlack(' README ')} no README.md found, a default one was created`);
     }
-    yield promises_1.default.writeFile(`${docsFolder}/README.md`, readMeContent);
-});
+    await fs.writeFile(path.join(options.docsFolder, target), content);
+};
+const STATUS_COLORS = {
+    [StatisticType.INCLUDE]: kleur.green,
+    [StatisticType.ERROR]: kleur.red,
+    [StatisticType.EMPTY]: kleur.yellow,
+    [StatisticType.EXCLUDE]: kleur.blue
+};
 /**
- * Parse all CLI arguments
- * @param {CLIArguments} argv
- * @returns {object} all arguments
+ * Print a status line
+ * @param {StatisticType} type
+ * @param {string} message
  */
-const parseArguments = (argv) => {
-    return {
-        include: (argv.include || '').split(',').filter(Boolean),
-        exclude: (argv.exclude || '').split(',').filter(Boolean),
-        srcFolder: argv.source.replace('./', ''),
-        codeFolder: argv.folder,
-        docsFolder: `${argv.dist}/${argv.folder}`,
-        title: argv.title,
-        readme: argv.readme,
-        rmPattern: argv.rmPattern || [],
-        partials: argv.partials || []
-    };
+const printStatus = (type, message) => {
+    console.log(STATUS_COLORS[type]()
+        .inverse()
+        .bold(` ${type.padEnd(7)} `), message);
 };
 /**
- * Default command that generate md files
- * @param {object} argv passed arguments
+ * Print the result of a parsed file
+ * @param {ParseReturn} entry
  */
-const generate = (argv) => __awaiter(void 0, void 0, void 0, function* () {
-    const { exclude, include, srcFolder, codeFolder, docsFolder, title, rmPattern } = parseArguments(argv);
-    const startTime = +new Date();
-    // remove docs folder, except README.md
-    const deletedPaths = yield (0, del_1.default)([`${docsFolder}/**/*`, ...rmPattern]);
-    const lsFolder = yield (0, list_folder_1.listFolder)(srcFolder, exclude, include);
-    yield (0, mkdirp_1.mkdirp)(docsFolder);
-    const parsePromises = [];
-    // print out all files
-    for (const file of lsFolder.paths) {
-        if (!file.isDir) {
-            node_readline_1.default.clearLine(process.stdout, 0);
-            node_readline_1.default.cursorTo(process.stdout, 0);
-            process.stdout.write(kleur_1.default.dim(` ${file.path} `));
-            yield new Promise((resolve) => setTimeout(resolve, 20));
+const printResult = (entry) => {
+    const source = `${kleur.dim(entry.file.folder)}${kleur.bold(path.basename(entry.file.path))}`;
+    if (entry.type === StatisticType.INCLUDE) {
+        printStatus(entry.type, `${source} → ${kleur.dim(entry.dest + '/')}${kleur.bold(entry.file.name + '.md')}`);
+    }
+    else if (entry.type === StatisticType.EMPTY) {
+        printStatus(entry.type, `${source} ${kleur.dim('(no documentation found)')}`);
+    }
+    else {
+        printStatus(entry.type, source);
+        if (entry.error) {
+            console.log(kleur.red(entry.error.replace(/^/gm, '          ')));
         }
     }
-    node_readline_1.default.clearLine(process.stdout, 0);
-    node_readline_1.default.cursorTo(process.stdout, 0);
-    // iterate through files and parse them
-    for (const file of lsFolder.paths) {
-        parsePromises.push((() => __awaiter(void 0, void 0, void 0, function* () {
-            const data = yield parseDirectoryFile(file, argv);
-            if (data && (data === null || data === void 0 ? void 0 : data.relativePathDest)) {
-                return (0, parser_1.writeContentToFile)(data, data.relativePathDest);
-            }
-        }))());
+};
+/**
+ * Default command that generates the markdown files
+ * @param {CLIArguments} argv passed arguments
+ * @returns {Promise<ParseReturn[]>} results of all parsed files
+ */
+export const generate = async (argv) => {
+    const options = parseArguments(argv);
+    const startTime = performance.now();
+    // the generated folder is always recreated
+    await fs.rm(options.docsFolder, { recursive: true, force: true });
+    if (options.rmPattern.length) {
+        await deleteAsync(options.rmPattern);
     }
-    // wait unitl all files resolved
-    let result = yield Promise.all(parsePromises);
-    result = result.filter(Boolean);
-    // write vuepress sidebar
-    yield createVuepressSidebar({
-        fileTree: lsFolder.tree,
-        srcFolder,
-        docsFolder,
-        codeFolder,
-        title
-    });
-    // print stats
+    await fs.mkdir(options.docsFolder, { recursive: true });
+    const lsFolder = await listFolder(options.srcFolder, options.exclude, options.include);
     for (const file of lsFolder.excluded) {
-        console.log(kleur_1.default.reset().inverse().bold().blue(' EXCLUDE '), `${kleur_1.default.dim(file.folder)}${kleur_1.default.bold(file.name + file.ext)}`);
+        printStatus(StatisticType.EXCLUDE, `${kleur.dim(file.folder)}${kleur.bold(path.basename(file.path))}`);
     }
-    console.log();
-    for (const entry of result.flat()) {
-        if (!entry.file)
-            continue;
-        const color = {
-            [constants_1.StatisticType.INCLUDE]: kleur_1.default.reset().inverse().bold().green,
-            [constants_1.StatisticType.ERROR]: kleur_1.default.reset().inverse().bold().red,
-            [constants_1.StatisticType.EMPTY]: kleur_1.default.reset().inverse().bold().yellow,
-            [constants_1.StatisticType.EXCLUDE]: kleur_1.default.reset().inverse().bold().blue
-        }[entry.type];
-        console.log(color(` ${entry.type} `), `${kleur_1.default.dim(entry.relativePathSrc)}${kleur_1.default.bold(entry.file.name + entry.file.ext)} \u2192 ${kleur_1.default.dim(entry.relativePathDest)}${kleur_1.default.bold(entry.file.name + '.md')}`);
+    const results = await mapLimit(lsFolder.paths, async (file) => {
+        const result = await processFile(file, options);
+        printResult(result);
+        return result;
+    });
+    await Promise.all([createVuepressSidebar(options, lsFolder.tree), createReadmeFile(options)]);
+    const count = (type) => results.filter((r) => r.type === type).length;
+    const resultTime = ((performance.now() - startTime) / 1000).toFixed(2);
+    console.log(`\n${kleur.green(`${count(StatisticType.INCLUDE)} generated`)}, ${kleur.yellow(`${count(StatisticType.EMPTY)} empty`)}, ${kleur.red(`${count(StatisticType.ERROR)} failed`)}, ${kleur.blue(`${lsFolder.excluded.length} excluded`)}`);
+    console.log(`⏰ Time: ${resultTime}s`);
+    if (argv.watch) {
+        watchFiles(argv);
     }
-    // create README.md
-    yield createReadmeFile(argv, deletedPaths);
-    const resultTime = (Math.abs(startTime - +new Date()) / 1000).toFixed(2);
-    console.log(`\n⏰ Time: ${resultTime}s`);
-    (0, exports.watchFiles)(argv);
-});
-exports.generate = generate;
+    return results;
+};
 /**
- * Watch files in source folder
+ * Watch files in source folder and update the generated markdown files
  * @param {CLIArguments} argv
+ * @returns {object} chokidar watcher
  */
-const watchFiles = (argv) => {
-    const { exclude, include, srcFolder, codeFolder, docsFolder, title } = parseArguments(argv);
-    if (argv.watch) {
-        console.log('\n---\n\n👀 watching files...');
-        const watcher = chokidar_1.default.watch([srcFolder, argv.readme, `${srcFolder}/README.md`].filter(Boolean), {
-            ignored: /(^|[\/\\])\../,
-            persistent: true
-        });
-        watcher.on('change', (path) => __awaiter(void 0, void 0, void 0, function* () {
-            var _a;
-            const lsFolder = yield (0, list_folder_1.listFolder)(srcFolder, exclude, include);
-            const file = lsFolder.paths.find((p) => p.path === path);
-            node_readline_1.default.clearLine(process.stdout, 0);
-            node_readline_1.default.cursorTo(process.stdout, 0);
-            if (path === 'README.md' || path === `${srcFolder}/README.md`) {
-                yield createReadmeFile(argv);
+export const watchFiles = (argv) => {
+    const options = parseArguments(argv);
+    const readmePath = path.resolve(options.readmePath);
+    console.log('\n---\n\n👀 watching files...');
+    const watcher = chokidar.watch([options.srcFolder, options.readme].filter((p) => Boolean(p)), {
+        ignored: (p) => /(^|[/\\])\.[^/\\]/.test(p) || p.includes('node_modules'),
+        ignoreInitial: true
+    });
+    let queue = Promise.resolve();
+    const update = (event, changedPath) => {
+        queue = queue.then(async () => {
+            try {
+                if (path.resolve(changedPath) === readmePath) {
+                    await createReadmeFile(options);
+                    return;
+                }
+                const { paths, tree } = await listFolder(options.srcFolder, options.exclude, options.include);
+                const file = paths.find((p) => path.resolve(p.path) === path.resolve(changedPath));
+                if (event === 'unlink') {
+                    const dir = normalizePath(path.dirname(changedPath));
+                    const name = getPageName(dir, path.basename(changedPath, path.extname(changedPath)));
+                    const dest = getDestFolder({ folder: dir }, options.srcFolder, options.docsFolder);
+                    await fs.rm(path.join(dest, `${name}.md`), { force: true });
+                    console.log(kleur.dim(`removed ${changedPath}`));
+                }
+                else if (file) {
+                    printResult(await processFile(file, options));
+                }
+                await createVuepressSidebar(options, tree);
             }
-            if (file) {
-                process.stdout.write(kleur_1.default.dim(`update ${file.name + file.ext}`));
-                (_a = parseDirectoryFile(file, argv)) === null || _a === void 0 ? void 0 : _a.then((data) => {
-                    if (data) {
-                        (0, parser_1.writeContentToFile)(data, data.relativePathDest);
-                    }
-                    createVuepressSidebar({
-                        fileTree: lsFolder.tree,
-                        srcFolder,
-                        docsFolder,
-                        codeFolder,
-                        title
-                    });
-                });
+            catch (e) {
+                console.error(e);
             }
-        }));
-    }
+        });
+    };
+    watcher.on('all', (event, p) => {
+        if (event === 'add' || event === 'change' || event === 'unlink')
+            update(event, p);
+    });
+    return watcher;
 };
-exports.watchFiles = watchFiles;

package/dist/interfaces.d.ts

@@ -1,32 +1,58 @@
+import { StatisticType } from './constants.js';
 export interface DirectoryFile {
+    /** Path of the file relative to the working directory, e.g. `src/lib/foo.ts` */
     path: string;
-    isDir: boolean;
-    ext?: string;
+    /** Name of the generated page without extension. `index` files are prefixed with their folder. */
     name: string;
-    folder?: string;
+    /** File extension, e.g. `.ts` */
+    ext: string;
+    /** Folder of the file relative to the working directory with a trailing slash, e.g. `src/lib/` */
+    folder: string;
 }
 export interface CLIArguments {
-    include: string;
-    exclude: string;
-    partials: string[];
-    rmPattern: string[];
-    folder: string;
-    jsDocConfigPath: string;
-    source: string;
-    dist: string;
-    title: string;
-    readme: string;
-    watch: boolean;
+    /** Pattern to include files/folders (comma separated or list) */
+    include?: string | string[];
+    /** Pattern to exclude files/folders (comma separated or list) */
+    exclude?: string | string[];
+    /** jsdoc2markdown partial templates */
+    partials?: string[] | string;
+    /** Additional glob patterns of files to remove before generating */
+    rmPattern?: string[] | string;
+    /** Folder inside the destination folder, default `code` */
+    folder?: string;
+    /** Path to a jsdoc config */
+    jsDocConfigPath?: string;
+    /** Source folder, default `./src` */
+    source?: string;
+    /** Destination folder, default `./documentation` */
+    dist?: string;
+    /** Title of the documentation, default `API` */
+    title?: string;
+    /** Path to a custom readme */
+    readme?: string;
+    /** Watch the source files */
+    watch?: boolean;
+    /** Make the top level sidebar groups collapsible, default `false` */
+    collapsible?: boolean;
+    /** Sidebar format of the generated `config.js`, default `vuepress` */
+    format?: 'vuepress' | 'vitepress';
+    /** Path to a config file */
+    config?: string;
 }
+/**
+ * Options of a `vuepress-jsdoc.config.js` file
+ */
+export type UserConfig = Omit<CLIArguments, 'config'>;
 export interface ParseReturn {
-    success: boolean;
+    /** Result of parsing */
+    type: StatisticType;
+    /** Destination folder relative to the working directory */
     dest: string;
     file: DirectoryFile;
+    /** Rendered markdown (including the frontmatter) */
     content: string;
-    empty: boolean;
-    excluded?: boolean;
-    relativePathSrc: string;
-    relativePathDest: string;
+    /** Error message, if the file could not be parsed */
+    error?: string;
 }
 export interface FileTree {
     name: string;

package/dist/interfaces.js

@@ -1,2 +1 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
+export {};

package/dist/lib/comment-parser.d.ts

@@ -1,17 +1,23 @@
-import { DirectoryFile } from '../interfaces';
+import { DirectoryFile } from '../interfaces.js';
+interface ParsedComment {
+    /** raw frontmatter string */
+    frontmatter: string | null;
+    /** parsed frontmatter attributes */
+    attributes: Record<string, any> | null;
+}
 /**
- * Search in file for @vuepress comment
+ * Search in file for a `@vuepress` comment block and parse its frontmatter
  * @param {string} fileContent content of given file
  * @returns {object} object of found frontmatter data
  */
-export declare const parseComment: (fileContent: string) => import("front-matter").FrontMatterResult<Record<string, string>> | {
-    frontmatter: null;
-    attributes: null;
-};
+export declare const parseComment: (fileContent: string) => ParsedComment;
 /**
- * Helper function to get header as structured markdown
+ * Helper function to get the header of a page as structured markdown.
+ * It contains the frontmatter and a headline (`# headline`).
+ * The headline is omitted for vue files, because vue-docgen-cli renders its own.
  * @param {string} content file content
- * @param {object} file file object
+ * @param {DirectoryFile} file file object
  * @returns {string} markdown header
  */
-export declare const parseVuepressFileHeader: (content: string, file: DirectoryFile) => string;
+export declare const parseVuepressFileHeader: (content: string, file: Pick<DirectoryFile, 'name' | 'ext'>) => string;
+export {};