Skip to content

Wrapper for the jsdoc command line tool for generating JSDoc HTML output

License

Notifications You must be signed in to change notification settings

mbland/jsdoc-cli-wrapper

Repository files navigation

JSDoc Command Line Interface Wrapper

Wrapper for the jsdoc command line tool for generating JSDoc HTML output. Removes the existing destination directory if it exists, runs jsdoc, and emits the relative path to the generated index.html file.

Source: https://github.com/mbland/jsdoc-cli-wrapper

License CI status Test results Coverage Status

Installation

You probably want to install the jsdoc CLI first, though the wrapper will kindly suggest you do so if it can't find it. Using pnpm to install it once for all your local projects:

pnpm add -g jsdoc

Then you're free to add this wrapper globally, or to a specific project. For example, to add it to your devDependencies:

pnpm add -D jsdoc-cli-wrapper

Usage

This wrapper passes every command line argument through to the jsdoc CLI as is and doesn't change the behavior of jsdoc itself at all. Use it exactly as you would use jsdoc on its own.

Motivation

The jsdoc command will:

  1. silently write new output into an existing directory, and
  2. not show where the generated index.html entrypoint resides.

While admittedly minor annoyances, they're still annoyances:

  1. It can be surprising to change the structure of your project, run jsdoc, and have stale files and directories laying around. This can make it inconvenient to find where the newly generated documentation actually is.

  2. Seeing the path to the new index.html helps make sure things end up where you expect. This is especially useful when the JavaScript code is embedded in a larger, possibly multilanguage repository. It also makes it far more convenient to copy the path and open it in a browser.

jsdoc doesn't have any command line options to deal with either of these issues. Not even --verbose nor --debug will show the path to index.html.

This wrapper resolves both of those minor annoyances.

Examples

This project

This project's 'jsdoc' script uses jsdoc.json as its configuration file, resulting in:

$ pnpm jsdoc

> jsdoc-cli-wrapper@1.0.0 jsdoc .../jsdoc-cli-wrapper
> node index.js -c jsdoc.json .

jsdoc/jsdoc-cli-wrapper/1.0.0/index.html

Of course, your own project would use jsdoc-cli-wrapper instead of node index.js. (This project uses the latter to ensure Windows compatibility during development.)

Multilanguage project

My mbland/tomcat-servlet-testing-example project uses Gradle to build both the frontend and backend into a common build/ directory. Its strcalc/src/main/frontend/jsdoc.json config looks like:

{
  "plugins": [ "plugins/markdown" ],
  "recurseDepth": 10,
  "source": {
    "includePattern": ".+\\.js$",
    "exclude": ["node_modules"]
  },
  "opts": {
    "destination": "../../../build/jsdoc",
    "recurse": true,
    "readme": "README.md",
    "package": "package.json"
  }
}

Its package.json contains a jsdoc script that runs this wrapper (before this repository existed, it used a local version):

$ cd strcalc/src/main/frontend
$ pnpm jsdoc

> tomcat-servlet-testing-example-frontend@0.0.0 jsdoc .../tomcat-servlet-testing-example/strcalc/src/main/frontend
> node bin/jsdoc-cli-wrapper.js -c ./jsdoc.json .

../../../build/jsdoc/tomcat-servlet-testing-example-frontend/0.0.0/index.html

Background

I developed this while experimenting with JSDoc on mbland/tomcat-servlet-testing-example. I was surprised and frustrated that the CLI was silent when it came to reporting where it emitted its output.

My first version of the wrapper was a short Bash script, which is available here as orig/jsdoc.sh. It was short and to the point, and used variations of sed and find that I'd somehow never used before. (In fact, that's the main reason why I'm keeping it around, for reference.)

It helped me move forward and was a great proof of concept, but was nowhere near as robust as the Node.js version in this package. It also wasn't natively portable to Windows. So I decided to dig in and make it so, using it as a Node.js, JSDoc, and npm packaging exercise as well.

About

Wrapper for the jsdoc command line tool for generating JSDoc HTML output

Resources

License

Stars

Watchers

Forks

Packages

No packages published