vuepress-jsdoc 5.0.0 → 6.1.0

package/README.md

@@ -8,73 +8,128 @@ This npm package serves as a command line script designed to analyze your JavaSc
 
 ![CLI ./example](https://user-images.githubusercontent.com/15351728/131877824-0124e47f-9080-4976-88d0-84ad04b64f24.gif)
 
-## Vuepress support
+## Requirements
 
-This npm package is compatible with VuePress 2; however, it requires a version lower than `5.0.0` for proper functionality with VuePress 1.
+- Node.js `>= 22.22`
+- VuePress 2 (use a version lower than `5.0.0` for VuePress 1)
 
 ## How to
 
 ```bash
-yarn global add vuepress-jsdoc
-npm i vuepress-jsdoc -g
+npm i -D vuepress-jsdoc
+# or
+pnpm add -D vuepress-jsdoc
 ```
 
 **Example:**
 
 ```bash
 # search code in src and move it to code (./documentation/code) in your vuepress folder (./documentation)
-vuepress-jsdoc --source ./src --dist ./documentation --folder code --title API --exclude="**/*/*.test.js"
+vuepress-jsdoc --source ./src --dist ./documentation --folder code --title API --exclude="**/*.test.js"
 ```
 
-You can also use `npx vuepress-jsdoc`, if you want.
+You can also run it without installing via `pnpm dlx vuepress-jsdoc` or `npx vuepress-jsdoc`.
 
-#### Watch-Mode `alpha`
+Every `.js`, `.jsx`, `.mjs`, `.cjs`, `.ts`, `.mts`, `.cts`, `.tsx` and `.vue` file is parsed. Files without any documentation are skipped, so they do not create empty pages. Files which can not be parsed are reported as `ERROR` with the reason and the command exits with code `1`.
 
-If you do not want to run`vuepress-jsdoc` again and again and again.
-You can simply pass `--watch` or `-w`.
+#### Watch-Mode
+
+If you do not want to run `vuepress-jsdoc` again and again and again.
+You can simply pass `--watch` or `-w`. Added, changed and removed files update the markdown files and the sidebar.
 
 ### Command-Options
 
 Use these options after `vuepress-jsdoc`.
 
-| Name              | Alias | Default         | Description                                                                                                                                     |
-| ----------------- | ----- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| --source          | -s    | ./src           | Source folder with .js or .ts files                                                                                                             |
-| --dist            | -d    | ./documentation | Destination folder                                                                                                                              |
-| --folder          | -f    | ./code          | Folder inside destination folder. Gets overwritten everytime                                                                                    |
-| --title           | -t    | API             | Title of your documentation                                                                                                                     |
-| --help            | -h    |                 | Show help                                                                                                                                       |
-| --version         | -v    |                 | Show current version                                                                                                                            |
-| --readme          | -r    |                 | Path to custom readme file                                                                                                                      |
-| --exclude         | -e    |                 | Pattern to exclude files/folders (Comma seperated) - \*.test.js,exclude.js [more information](https://github.com/micromatch/micromatch#ismatch) |
-| --include         | -e    |                 | Pattern to include files/folders (Comma seperated) - \*.test.js,exclude.js [more information](https://github.com/micromatch/micromatch#ismatch) |
-| --rmPattern       | -rm   |                 | Pattern when removing files. You can ex- and include files. (glob pattern)                                                                      |
-| --partials        | -p    |                 | jsdoc2markdown partial templates (overwrites default ones)                                                                                      |
-| --jsDocConfigPath | -c    |                 | Path to [JsDoc Config](http://usejsdoc.org/about-configuring-jsdoc.html) (experimental)                                                         |
-| --watch           | -w    |                 | Watch changes and update markdown files                                                                                                         |
+| Name              | Alias | Default         | Description                                                                                                                                          |
+| ----------------- | ----- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| --source          | -s    | ./src           | Source folder with .js, .ts or .vue files                                                                                                            |
+| --dist            | -d    | ./documentation | Destination folder                                                                                                                                   |
+| --folder          | -f    | code            | Folder inside destination folder. Gets overwritten everytime                                                                                         |
+| --title           | -t    | API             | Title of your documentation                                                                                                                          |
+| --help            | -h    |                 | Show help                                                                                                                                            |
+| --version         | -V    |                 | Show current version                                                                                                                                 |
+| --readme          | -r    |                 | Path to custom readme file                                                                                                                           |
+| --exclude         | -e    |                 | Pattern to exclude files/folders (comma separated) - \*\*/\*.test.js,exclude.js [more information](https://github.com/micromatch/micromatch#ismatch) |
+| --include         | -i    |                 | Pattern to include files/folders (comma separated) - \*\*/\*.js,include.js [more information](https://github.com/micromatch/micromatch#ismatch)      |
+| --rmPattern       | --rm  |                 | Additional glob patterns of files to remove before generating                                                                                        |
+| --partials        | -p    |                 | jsdoc2markdown partial templates (overwrites default ones)                                                                                           |
+| --jsDocConfigPath | -c    |                 | Path to [JsDoc Config](https://jsdoc.app/about-configuring-jsdoc.html)                                                                               |
+| --watch           | -w    |                 | Watch changes and update markdown files                                                                                                              |
+| --collapsible     |       |                 | Make the top level sidebar groups collapsible (nested folders are always collapsible)                                                                |
+| --format          |       | vuepress        | Sidebar format of the generated `config.js`: `vuepress` or `vitepress`                                                                               |
+| --config          |       |                 | Path to a config file (default: `vuepress-jsdoc.config.{js,mjs,cjs,json}`)                                                                           |
+
+Patterns are matched relative to the source folder. Folders can be excluded as a whole, e.g. `--exclude="**/__tests__"`.
+
+### Config file
+
+Instead of command options, you can add a `vuepress-jsdoc.config.js` (or `.mjs`, `.cjs`, `.json`) to your project. It is loaded automatically, or use `--config ./path/to/config.js`. Command options win over the config file.
+
+```javascript
+// vuepress-jsdoc.config.js
+import { defineConfig } from 'vuepress-jsdoc';
+
+export default defineConfig({
+  source: './src',
+  dist: './documentation',
+  title: 'API',
+  exclude: ['**/__tests__', '**/*.test.js']
+});
+```
 
 ### config.js
 
-Inside your generated folder, you can find a `config.js`.
-This file includes a complete filetree and an vuepress sidebar tree.
+Inside your generated folder, you can find a `config.js` (ES module).
+It exports the complete `fileTree` and a `sidebarTree(title)` function, which returns a VuePress 2 sidebar. Every folder becomes a sidebar group.
+
+## VuePress plugin
+
+The easiest way: add the plugin to your VuePress config. It generates the documentation when VuePress starts, updates it during `vuepress dev` and adds the sidebar to all generated pages. No separate CLI call is needed.
+
+```javascript
+// documentation/.vuepress/config.js
+import { viteBundler } from '@vuepress/bundler-vite';
+import { defaultTheme } from '@vuepress/theme-default';
+import { defineUserConfig } from 'vuepress';
+import { vuepressJsdocPlugin } from 'vuepress-jsdoc';
+
+export default defineUserConfig({
+  bundler: viteBundler(),
+  theme: defaultTheme({
+    navbar: [{ text: 'Code', link: '/code/' }]
+  }),
+  plugins: [
+    vuepressJsdocPlugin({
+      source: './src',
+      folder: 'code',
+      exclude: ['**/__tests__'],
+      // text of the readme link in the sidebar
+      sidebarTitle: 'Readme'
+    })
+  ]
+});
+```
+
+The plugin accepts the same options as the config file, except `dist` (the VuePress source folder is used), `watch` and `format`. Set `sidebar: false` if you configure the sidebar in your theme yourself. Paths are relative to the working directory.
 
 ## How to configure vuepress
 
-[Vuepress](https://vuepress.vuejs.org/) is a static site generator by Evan You.
+[VuePress](https://vuepress.vuejs.org/) is a static site generator.
 You can add all generated documentation files to your existing vuepress project or create a new one.
 
 ```bash
 # First install vuepress
-yarn global add vuepress
+pnpm add -D vuepress@next @vuepress/bundler-vite@next @vuepress/theme-default@next sass-embedded
 
 # Run the CLI
-vuepress-jsdoc
+pnpm exec vuepress-jsdoc
 
 # Run vuepress dev server
-vuepress dev ./documentation
+pnpm exec vuepress dev ./documentation
 
 # Run vuepress build, if you want to ship it
-vuepress build ./documentation
+pnpm exec vuepress build ./documentation
 ```
 
 **Access it via:** [http://localhost:8080/code/](http://localhost:8080/code/)
@@ -85,35 +140,52 @@ Create a `.vuepress` folder inside the `documentation` folder and add the follow
 **config.js:**
 
 ```javascript
+import { viteBundler } from '@vuepress/bundler-vite';
+import { defaultTheme } from '@vuepress/theme-default';
+import { defineUserConfig } from 'vuepress';
+
 // auto generated sidebar
-const { sidebarTree } = require('../code/config');
-
-module.exports = {
-  dest: 'dist',
-  locales: {
-    '/': {
-      title: 'vuepress-jsdoc',
-      description: 'Generate jsdoc markdown files for vuepress'
+import { sidebarTree } from '../code/config.js';
+
+export default defineUserConfig({
+  bundler: viteBundler(),
+  title: 'vuepress-jsdoc',
+  description: 'Generate jsdoc markdown files for vuepress',
+  theme: defaultTheme({
+    navbar: [
+      { text: 'Home', link: '/' },
+      { text: 'Code', link: '/code/' }
+    ],
+    // Add the generated sidebar
+    sidebar: {
+      ...sidebarTree('Mainpage title')
     }
-  },
+  })
+});
+```
+
+## VitePress
+
+Use `--format vitepress` to generate a [VitePress](https://vitepress.dev/) sidebar. The readme is written to `index.md`, because VitePress uses it as the page of a folder.
+
+The documentation of this project is a VitePress site generated this way, see [`documentation/.vitepress/config.mjs`](./documentation/.vitepress/config.mjs).
+
+```bash
+vuepress-jsdoc --source ./src --dist ./docs --folder code --format vitepress
+```
+
+```javascript
+// docs/.vitepress/config.mjs
+import { defineConfig } from 'vitepress';
+
+import { sidebarTree } from '../code/config.js';
+
+export default defineConfig({
   themeConfig: {
-    editLinks: true,
-    sidebarDepth: 4,
-    docsDir: 'code',
-    locales: {
-      '/': {
-        nav: [
-          {
-            text: 'Home',
-            link: '/'
-          }
-        ],
-        // Add the generated sidebar
-        sidebar: Object.assign({}, sidebarTree('Mainpage title'))
-      }
-    }
+    nav: [{ text: 'Code', link: '/code/' }],
+    sidebar: sidebarTree('Overview')
   }
-};
+});
 ```
 
 ## Custom readme
@@ -138,39 +210,66 @@ Enhance your page customization by incorporating custom metadata through the `@v
 
 Use `headline` to add a custom `h1` title.
 
-[More information](https://vuepress.vuejs.org/guide/markdown.html#front-matter)
+[More information](https://vuepress.vuejs.org/guide/page.html#frontmatter)
 
 ## Typescript
 
-To integrate TypeScript support, install the following dev-dependencies with the following command:
+TypeScript files work out of the box. The types are removed with the type stripping of Node.js before the file is passed to jsdoc, so all comments and line numbers stay intact.
+
+Syntax which has to be transformed (`enum`, `namespace`, parameter properties) and `.tsx` files are transpiled with the TypeScript compiler of your project. `typescript` 6 or lower (or `@typescript/typescript6`) has to be installed for this, because `typescript` 7 has no JavaScript API.
+
+If you need more control, use babel instead. Install the following dev-dependencies:
 
 ```bash
-npm install -D typescript jsdoc-babel @babel/cli @babel/core @babel/preset-env @babel/preset-typescript jsdoc-to-markdown
+pnpm add -D jsdoc-babel @babel/core @babel/preset-env @babel/preset-typescript
 ```
 
 After installation, include a `jsdoc.json` file in your project with specific settings, and reference it using the `-c` parameter. For a comprehensive example with all the necessary configurations, refer to the `./example` folder. The example also demonstrates the usage of Babel plugins.
 
 ## Example
 
-The `./example` folder includes a full working vuepress-jsdoc example.
+The `./example` folder includes a full working vuepress-jsdoc example. It is part of the pnpm workspace and uses the local build of `vuepress-jsdoc`.
 
 ```bash
-# Install dependencies
-npm install
+# Install dependencies (from the repository root)
+pnpm install
+pnpm build
 
-# Run the CLI
-vuepress-jsdoc
+cd example
 
 # Generate docs
-npm run docs
+pnpm run docs
 
-# Run dev server
-npm run dev
+# Generate docs and run the dev server
+pnpm run dev
 
-# Generate dist folder
-npm run build
+# Generate docs and build the dist folder
+pnpm run build:local
 ```
 
+## Migrating from 5.x
+
+- Node.js `>= 22.22` is required.
+- The generated `config.js` is an ES module. Import it with `import { sidebarTree } from '../code/config.js'`.
+- VuePress 2 needs a bundler in your config: `bundler: viteBundler()` from `@vuepress/bundler-vite`.
+- Sidebar groups use `collapsible` instead of `collapsable`.
+- `--rmPattern` is also available as `--rm`. The generated folder is always recreated.
+- Files without documentation no longer create empty pages.
+
 ## Contribute
 
 PRs are always welcome (:
+
+This project uses [pnpm](https://pnpm.io/).
+
+```bash
+pnpm install
+pnpm test        # vitest
+pnpm lint        # eslint (pnpm lint:fix to fix)
+pnpm typecheck   # tsc
+pnpm build       # compile to ./dist
+pnpm run docs:dev    # VitePress dev server for the documentation of this project
+pnpm run docs:build  # build it to ./public
+```
+
+Use `pnpm run docs` instead of `pnpm docs`, because `pnpm docs` is a builtin pnpm command.

package/bin/vuepress-jsdoc.js

@@ -1,5 +1,8 @@
 #!/usr/bin/env node
-'use strict';
-Object.defineProperty(exports, '__esModule', { value: true });
-const { version } = require('../package.json');
-require('../dist/cmds').default(version);
+import { readFileSync } from 'node:fs';
+
+import cli from '../dist/cmds.js';
+
+const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf-8'));
+
+cli(version);

package/dist/cmds.d.ts

@@ -3,6 +3,8 @@
  * we need the version from the package.json here. We do not import
  * this here, because otherwise the folder structure in the dist folder would get mixed up.
  * @param {string} version a version string
+ * @param {string[]} argv process arguments
+ * @returns {Promise<void>}
  */
-declare const _default: (version: string) => void;
-export default _default;
+export declare const cli: (version: string, argv?: string[]) => Promise<void>;
+export default cli;

package/dist/cmds.js

@@ -1,34 +1,61 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
 /*
  * @vuepress
  * ---
- * headline: cmds.ts
+ * title: CLI
+ * headline: Command line interface
  * ---
  */
-const commander_1 = require("commander");
-const _1 = require(".");
+import { Command, Option } from 'commander';
+import { generate } from './index.js';
+import { loadConfig } from './lib/config.js';
+import { StatisticType } from './constants.js';
 /**
  * This method builds the cli interface and is necessary because
  * we need the version from the package.json here. We do not import
  * this here, because otherwise the folder structure in the dist folder would get mixed up.
  * @param {string} version a version string
+ * @param {string[]} argv process arguments
+ * @returns {Promise<void>}
  */
-exports.default = (version) => {
-    commander_1.program.version(version).description('a CLI Tool to generate markdown files for vuepress');
-    commander_1.program
-        .description('Generate the md files')
-        .option('-s, --source <string>', 'Source folder with .js or .ts files', './src')
+export const cli = async (version, argv = process.argv) => {
+    const program = new Command();
+    program
+        .name('vuepress-jsdoc')
+        .version(version)
+        .description('Generate markdown files for VuePress out of your JSDoc comments')
+        .option('-s, --source <string>', 'Source folder with .js, .ts or .vue files', './src')
         .option('-d, --dist <string>', 'Destination folder', './documentation')
         .option('-f, --folder <string>', 'Folder inside destination folder. Gets overwritten everytime', 'code')
         .option('-t, --title <string>', 'Title of your documentation', 'API')
         .option('-r, --readme <string>', 'Path to your custom readme')
-        .option('-i, --include <string>', 'Pattern to include files/folders (Comma seperated) - *.test.js,include.js')
-        .option('-e, --exclude <string>', 'Pattern to exclude files/folders (Comma seperated) - *.test.js,exclude.js')
-        .option('-w, --watch', 'This flag watches your source files')
-        .option('-rm, --rmPattern [files...]', 'Pattern when removing files. You can ex- and include files. (glob pattern)', '')
-        .option('-p, --partials [files...]', 'jsdoc2markdown partial templates (overwrites default ones)', '')
+        .option('-i, --include <string>', 'Pattern to include files/folders (comma separated) - **/*.js,include.js')
+        .option('-e, --exclude <string>', 'Pattern to exclude files/folders (comma separated) - **/*.test.js,exclude.js')
+        .option('-w, --watch', 'Watch your source files and update the documentation')
+        .option('--collapsible', 'Make the top level sidebar groups collapsible')
+        .option('--rm, --rmPattern [files...]', 'Additional glob patterns of files to remove before generating')
+        .option('-p, --partials [files...]', 'jsdoc2markdown partial templates (overwrites default ones)')
         .option('-c, --jsDocConfigPath <string>', 'Path to jsdoc config')
-        .action(_1.generate);
-    commander_1.program.parse(process.argv);
+        .addOption(new Option('--format <format>', 'Sidebar format of the generated config.js')
+        .choices(['vuepress', 'vitepress'])
+        .default('vuepress'))
+        .option('--config <path>', 'Path to a config file (default: vuepress-jsdoc.config.{js,mjs,cjs,json})')
+        .action(async (cliOptions) => {
+        const loaded = await loadConfig(cliOptions.config);
+        const options = { ...cliOptions };
+        if (loaded) {
+            console.log(`Using config ${loaded.path}`);
+            // options of the command line win over the config file, the config file wins over the defaults
+            for (const [key, value] of Object.entries(loaded.config)) {
+                if (program.getOptionValueSource(key) !== 'cli') {
+                    options[key] = value;
+                }
+            }
+        }
+        const results = await generate(options);
+        if (!options.watch && results.some((r) => r.type === StatisticType.ERROR)) {
+            process.exitCode = 1;
+        }
+    });
+    await program.parseAsync(argv);
 };
+export default cli;

package/dist/constants.d.ts

@@ -4,3 +4,19 @@ export declare enum StatisticType {
     INCLUDE = "INCLUDE",
     EXCLUDE = "EXCLUDE"
 }
+/**
+ * File extensions which are parsed with jsdoc-to-markdown
+ */
+export declare const SCRIPT_EXTENSIONS: string[];
+/**
+ * File extensions which are parsed with vue-docgen-cli
+ */
+export declare const VUE_EXTENSIONS: string[];
+/**
+ * TypeScript extensions. These need their types stripped before jsdoc can read them.
+ */
+export declare const TYPESCRIPT_EXTENSIONS: string[];
+/**
+ * Placeholder inside the generated sidebar, which gets replaced with the title passed to `sidebarTree(title)`
+ */
+export declare const SIDEBAR_TITLE_PLACEHOLDER = "::vuepress-jsdoc-title::";

package/dist/constants.js

@@ -1,10 +1,23 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.StatisticType = void 0;
-var StatisticType;
+export var StatisticType;
 (function (StatisticType) {
     StatisticType["EMPTY"] = "EMPTY";
     StatisticType["ERROR"] = "ERROR";
     StatisticType["INCLUDE"] = "INCLUDE";
     StatisticType["EXCLUDE"] = "EXCLUDE";
-})(StatisticType || (exports.StatisticType = StatisticType = {}));
+})(StatisticType || (StatisticType = {}));
+/**
+ * File extensions which are parsed with jsdoc-to-markdown
+ */
+export const SCRIPT_EXTENSIONS = ['.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx', '.mts', '.cts'];
+/**
+ * File extensions which are parsed with vue-docgen-cli
+ */
+export const VUE_EXTENSIONS = ['.vue'];
+/**
+ * TypeScript extensions. These need their types stripped before jsdoc can read them.
+ */
+export const TYPESCRIPT_EXTENSIONS = ['.ts', '.tsx', '.mts', '.cts'];
+/**
+ * Placeholder inside the generated sidebar, which gets replaced with the title passed to `sidebarTree(title)`
+ */
+export const SIDEBAR_TITLE_PLACEHOLDER = '::vuepress-jsdoc-title::';

package/dist/index.d.ts

@@ -1,11 +1,51 @@
-import { CLIArguments } from './interfaces';
+import { CLIArguments, ParseReturn } from './interfaces.js';
+import { FileTree } from './interfaces.js';
+import { SidebarOptions } 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';
+export type { CLIArguments, DirectoryFile, FileTree, ParseReturn, UserConfig } from './interfaces.js';
 /**
- * Default command that generate md files
- * @param {object} argv passed arguments
+ * Parse all CLI arguments
+ * @param {CLIArguments} argv
+ * @returns {object} all arguments
+ */
+export declare const parseArguments: (argv: CLIArguments) => {
+    include: string[];
+    exclude: string[];
+    srcFolder: string;
+    codeFolder: string;
+    docsFolder: string;
+    title: string;
+    readme: string | undefined;
+    readmePath: string;
+    rmPattern: string[];
+    partials: string[];
+    jsDocConfigPath: string | undefined;
+    collapsible: boolean;
+    format: "vitepress" | "vuepress";
+};
+export type Options = ReturnType<typeof parseArguments>;
+/**
+ * Get the sidebar options of the given file tree
+ * @param {Options} options
+ * @param {FileTree[]} fileTree created by `listFolder`
+ * @returns {SidebarOptions}
+ */
+export declare const getSidebarOptions: (options: Options, fileTree: FileTree[]) => SidebarOptions;
+/**
+ * Default command that generates the markdown files
+ * @param {CLIArguments} argv passed arguments
+ * @returns {Promise<ParseReturn[]>} results of all parsed files
  */
-export declare const generate: (argv: CLIArguments) => Promise<void>;
+export declare const generate: (argv: CLIArguments) => Promise<ParseReturn[]>;
 /**
- * Watch files in source folder
+ * Watch files in source folder and update the generated markdown files
  * @param {CLIArguments} argv
+ * @returns {object} chokidar watcher
  */
-export declare const watchFiles: (argv: CLIArguments) => void;
+export declare const watchFiles: (argv: CLIArguments) => import("chokidar").FSWatcher;