Is there a detailed documentation on how to create own jsdoc templates?

Question

Short version: If I wanted to develop a completely new jsDoc template from scratch, what would I have to read to understand what jsDoc does, what interface my template must provide and what data I get to work with?

Long version: I've been using jsDoc for a while now and have come across some tags that I would like to add and overview pages that I would like to have generated out of my documentation. Up to now I solved all my "user problems" with usejsdoc.org. I even managed to add a new jsdoc plugin that adds some tags. However, I can't find any developer documentation on how to create templates for jsdoc. I use ink-docstrap so I clicked my way through the template-folder (publish.js, /tmpl, etc.) and somehow got the idea of how everything works. But its very very time consuming.

What should I read to become a jsDoc template pro?

Answer 1

I am running into a similar difficulty with lack of documentation. There is a GitHub issue that has been open for 7 years on this: Provide docs that explain how templates work.

The only example I've found so far of a custom template that doesn't look like just a modified version of the default is Ramda's documentation. It looks like they use a completely custom publish.js script that uses handlebars.js instead of underscore.js templates, constructs a non-hierarchical nav, pulls info from @sig and @category tags, and uses links to github for 'view source' instead of rendering its own html pages for source code.

Some of their code will be difficult to understand unless you are familiar with Ramda and functional programming (they use Ramda itself in their version of publish.js) but dumping out the values of data and docs during execution should help provide insight into what is going on.

It is helpful as well that their template is a single file so you don't have to jump between a lot of partial template files to follow how the doc is constructed.

Answer 2

These instructions are the closest I could find:

To create or use your own template:

1. Create a folder with the same name as your template (for example, mycooltemplate).
2. Within the template folder, create a file named publish.js. This file must be a CommonJS module that exports a method named publish.

For example:

/** @module publish */

/**
 * Generate documentation output.
 *
 * @param {TAFFY} data - A TaffyDB collection representing
 *                       all the symbols documented in your code.
 * @param {object} opts - An object with options information.
 */
exports.publish = function(data, opts) {
    // do stuff here to generate your output files
};

To invoke JSDoc 3 with your own template, use the -t command line option, and specify the path to your template folder:

./jsdoc mycode.js -t /path/to/mycooltemplate

Failing that, you can read the source code!