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
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
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.
The jsdoc
command will:
- silently write new output into an existing directory, and
- not show where the generated
index.html
entrypoint resides.
While admittedly minor annoyances, they're still annoyances:
-
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. -
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.
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.)
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
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.