Jsdoc: command-line argument for live-reload ?

[didaquis]

There are some way to implement live-reload of docs? I was thinking in something like:
jsdoc -c ./conf_jsdoc.json -r --live-reload

[JustinBeaudry]

jsdoc -c ./conf_jsdoc.json -r --live-reload

IMO, this is better left to the user (developer). Here's how I handle this.

Overview

Nodemon, to monitor source code for changes and recompile the docs, a LiveReload server to trigger refresh events in your browser and a LiveReload client to listen to those changes and reload the page.

LiveReload client

Recommended (browser extension)

Use the LiveReload Chrome extension or if using Safari/Firefox use the appropriate extension.

Alternative (custom layout, i.e., extra work)

If you don't want to/can't use a browser extension you would have to copy and modify your templates layout.tmpl to add a script tag:

<script>document.write('<script src="http://'
    + (location.host || 'localhost').split(':')[0]
    + ':35729/livereload.js?snipver=1"></'
    + 'script>')</script>

and update your jsdoc config to use your custom layout.tmpl instead of the default:

  "templates": {
    "default": {
      "layoutFile": "layout.tmpl"
    }
  }

If using a custom layout.tmpl it might be best to use a .js config file to conditionally include the LiveReload script if NODE_ENV=dev|development to prevent LiveReload from being included in your production docs.

caveat to a custom layout.tml: The template has to support overriding the layoutFile. The included (default) templates in jsdoc and Minami support this. You can check the publish.js of your template source to see if it includes conf.default.layoutFile to verify that this strategy will work.

Setup

Install dependencies

npm i -D livereload nodemon

Watch commands

Now let's set up the commands to watch for changes in both the source code and the compiled docs.

Legend

Some terms used in the following commands:

• out is the jsdoc output directory (the default), adjust as per your config.
• src is your application codes source directory See the nodemon README for the cli docs on how to watch a single file, multiple directories, etc., adjust as per your application.
• npx refers to locally installed packages, i.e., npm i -D nodemon, alternatively you could use a globally installed version, e.g. npm i -g nodemon and remove the npx prefix.

Recompiling docs on source code change

To watch for changes to your source code and recompile your docs:

npx nodemon --exec 'npx jsdoc -c conf_jsdoc.json' --watch src

Signal the LiveReload client to reload the browser page on docs change

To start a LiveReload server to send a refresh event to the LiveReload client when the docs are changed:

npx livereload out

Add some helpers in your package.json scripts

To make it a bit easier I usually include these commands as npm scripts (or a Makefile):

{
  "scripts": {
    "build:docs": "npx jsdoc -c conf_jsdoc.json",
    "watch:doc-src": "npx nodemon --exec 'npm run build:docs' --watch src",
    "watch:doc-output": "npx livereload out",
    "watch:docs": "npm run watch:doc-output & npm run watch:doc-src"
  }
}

Aside on unix commands and job control (Linux/MacOS)

Note that watch:docs is using Unix job control (skip if you're familiar), i.e., tell the shell to run both commands in the background. This is used because both nodemon and livereload will not exit until a SIGINT (CTRL+C) is sent to the shell so you cannot use && or ; since that will tell the shell to wait for the previous command to complete before starting the next.

Windows caveats

If you're using windows, you'll need to update watch:docs to be:

(npm run watch:jsdoc-output & npm run watch:jsdoc-src)

Which will group the commands. I haven't confirmed this to work, this is just from memory

Running

Now you can run:

npm run watch:docs

Which will start both nodemon and livereload.

Now when you make changes to your source code the jsdoc cli will be called to generate your docs to your output directory, and livereload (the LiveReload server) will listen for changes to your docs and trigger a reload event to the LiveReload client.

Killing Commands

Send a SIGINT CTRL+C to the shell to kill both commands.

Serving Docs

If using the a LiveReload browser extension it might be more straightforward to serve them from an HTTP server rather than from disk, i.e. file:/// I personally just use python -m SimpleHTTPServer to accomplish this, and usually add an npm script:

{
  "scripts": {
    "serve:docs": "cd out && python -m SimpleHTTPServer"
  }
}

Now you can:

npm run serve:docs

To start an HTTP server on port 8000. Now you can view your docs in the browser at localhost:8000.

Watch and Serve in a single command

As a convenience I usually make a single command to both watch and serve the docs:

{
  "scripts": {
    "docs:dev": "npm run build:docs && npm run watch:docs & npm run serve:docs"
  }
}

note that this first builds the docs and then watches and serves. This ensures that serve:docs will not exit due to the docs output directory not existing

Now you can run:

npm run docs:dev

To watch and serve the docs! For production docs, you can just use npm run build:docs (as defined above) to generate the output documentation.

[hegemonic]

I agree that this is better left to another tool. Thanks for the details about your setup, @JustinBeaudry!