10

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?

codepearlex
  • 442
  • 3
  • 14

3 Answers3

7

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!

Community
  • 1
  • 1
Alex
  • 7,405
  • 5
  • 46
  • 72
0

I've just published my own new jsdoc theme. What I did is I simply copied the default template: https://github.com/jsdoc3/jsdoc/tree/master/templates/default, and worked on that.

I also managed to add grunt with the following features: * transcompile + minify js files * parse sass styles and minify them * refresh the docs when you change something

You can see how it works here: https://github.com/SoftwareBrothers/better-docs

wojtekk
  • 516
  • 4
  • 7
0

you can customize one of existing templates (default, haruki or silent):

  • go into node_modules/jsdoc/template and grab on of them into your app directory outside node_modules.

  • feel free to rename the dir ex: jsdoc-template.

  • open jsdoc-template update/customize the content as you want.
    ex: open publish.js find Home and replace My Js App.

  • update jsdoc.json by adding:

"opts": {
  "template": "jsdoc-template"
}

another option to use one of those templates too: jsdoc3 template list examples

Muhammed Moussa
  • 2,045
  • 19
  • 15
  • That's right, customizing an existing template is probably the easiest solution. But I specifically asked for "detailed documentation on how to create own jsdoc templates", because customizing an existing template also requires a basic understanding of how jsdoc works, and I don't want to get that understanding by reading source code. – codepearlex Mar 02 '21 at 17:14