Theme API 2.0

[jfirebaugh]

Custom themes are modules that export:

/**
 * @function
 * @param {Array<Object>} comments
 * @param {Object} options
 * @param {ThemeCallback} callback
 */

/**
 * @callback ThemeCallback
 * @param {?Error} error
 * @param {?Array<vinyl.File>} output
 */

Implements #248.

[anandthakker]

This is great.

Couple questions:

1. I'm wondering about what options, exactly, the theme modules should receive. Should they just be the formatterOptions, or could it be useful for a theme to also get a copy of the options that were used for documentation itself?
2. Technically, this makes --format html a bit inaccurate, since a theme could now produce, e.g., a directory full of markdown files or something else entirely. Not sure what a better name would be, though--certainly html covers the majority of use cases. I suppose it would even be possible to drop --format entirely, moving the markdown output to documentation-theme-md-default and having quick aliases for it and the default html theme. Not sure if I like that or not, though...

[tmcw]

Have you tested that this will work with relative paths with the CLI? I'm worried that specifying, for instance -t ./my-theme will look for that theme within lib/output/, rather than the CWD

[tmcw]

Code looks solid, made one note about confirming that relative paths still work.

I see how the --html option could now be abused, but I think this is fine; making the name more broad would make it harder to grasp, trying to 'enforce' HTML output would be tricky and error-prone.

Markdown used to be templatable, like HTML, before the mdast switch. I think Markdown output is less... dying for customization relatively, but it's true that eventually we'll want to make it swappable. But for now, especially with upcoming CLI switches for the Markdown output, I'd like to keep it in core.

I'd prefer keeping options limited to formatterOptions - these could include a larger subset of the options down the line, but it's important to keep the "what options do i get" API controlled & consistent, otherwise HTML output could be broken by unrelated API changes.

[anandthakker]

Okay, sold on both points. Re: keeping html as the name here, it's nice that it can be hacked/abused for other purposes if people want to--and I think we should keep it that way--but I agree that the options should communicate the simpler, much more common use.

@tmcw Also agree re: formatterOptions and API stability. Separate but slightly related: it might be nice if there were a way to pass cli options through to a theme. I happen to like browserify's subarg approach, e.g. --theme [ my-pretty-theme --option1 --option2 ] (though unfortunately I don't think yargs would handle that). I guess another possibility is to punt by saying that themes that want to be configurable can just deal with their own config file in the cwd.

[trusktr]

This feature seems awesome. Is it documented yet? Any example of how to use this API?

[jfirebaugh]

@trusktr Yep, see https://github.com/documentationjs/documentation/blob/master/docs/THEMING.md.

[trusktr]

@jfirebaugh Nice. So, how does the module get registered with documentation.js? Is it a command line option, where the option matches the name of the module (just making a complete guess)?