Theme API 2.0

Author: jfirebaugh

README.md

@@ -50,7 +50,7 @@ lets you run `documentation` as a [Gulp](http://gulpjs.com/) build task.
 * [Node API](docs/NODE_API.md): documentation.js's self-generated documentation
 * [FAQ](docs/FAQ.md)
 
-* [Theming HTML](docs/THEME_HTML.md): tips for theming documentation output in HTML
+* [Theming](docs/THEMING.md): tips for theming documentation output in HTML
 * [See also](docs/SEE_ALSO.md): a list of projects similar to documentation.js
 
 ## User Guide

docs/THEME_HTML.md

@@ -1,27 +1,24 @@
-This assumes you have node.js installed:
+Documentation.js supports customizable themes for HTML output. A theme is a Node.js
+module that exports a single function with the following signature:
 
-First install dev-documentation:
-
-```
-npm install -g [email protected]
 ```
+/**
+ * @function
+ * @param {Array<Object>} comments - an array of comments to be output
+ * @param {Object} options - theme options
+ * @param {ThemeCallback} callback - see below
+ */
 
-Get a JSDoc-documented project to test against:
-
+/**
+ * @callback ThemeCallback
+ * @param {?Error} error
+ * @param {?Array<vinyl.File>} output
+ */
 ```
-git clone [email protected]:mapbox/mapbox-gl-js.git
-```
-
-Get a checkout of the default style
 
-```
-[email protected]:documentationjs/documentation-theme-default.git
-```
-
-Now start theming
-
-```
-dev-documentation mapbox-gl-js/js/mapbox-gl.js -t ./documentation-theme-default/
-```
+The theme function should call the callback with either an error, if one occurs,
+or an array of [vinyl](https://github.com/gulpjs/vinyl) `File` objects.
 
-If you have [LiveReload](https://chrome.google.com/webstore/detail/livereload/jnihajbhpnppcggbcgedagnkighmdlei) installed, you can enable it and it'll automatically refresh the page when you edit the theme.
+The theme is free to implement HTML generation however it chooses. See
+[the default theme](https://github.com/documentationjs/documentation-theme-default/)
+for some ideas.

docs/THEMING.md

@@ -1,13 +1,7 @@
 'use strict';
 
-var File = require('vinyl'),
-  vfs = require('vinyl-fs'),
-  concat = require('concat-stream'),
-  Handlebars = require('handlebars'),
-  walk = require('../walk'),
-  getTemplate = require('../get_template'),
-  resolveTheme = require('../resolve_theme'),
-  helpers = require('../html_helpers'),
+var walk = require('../walk'),
+  path = require('path'),
   hljs = require('highlight.js');
 
 /**
@@ -49,38 +43,17 @@ function highlight(comment, options) {
  *
  * @param {Array<Object>} comments parsed comments
  * @param {Object} options Options that can customize the output
- * @param {string} [options.theme] Name of a module used for an HTML theme.
+ * @param {string} [options.theme='documentation-theme-default'] Name of a module used for an HTML theme.
  * @param {Function} callback called with array of results as vinyl-fs objects
  * @returns {undefined} calls callback
  * @name html
  */
 module.exports = function makeHTML(comments, options, callback) {
   options = options || {};
   comments = walk(comments, highlight, options);
-
-  var themeModule = resolveTheme(options.theme);
-  var pageTemplate = getTemplate(Handlebars, themeModule, 'index.hbs');
-
-  Handlebars.registerPartial('section',
-    getTemplate(Handlebars, themeModule, 'section.hbs'));
-
-  var paths = comments.map(function (comment) {
-    return comment.path.join('.');
-  }).filter(function (path) {
-    return path;
-  });
-
-  helpers(Handlebars, paths);
-
-  // push assets into the pipeline as well.
-  vfs.src([themeModule + '/assets/**'], { base: themeModule })
-    .pipe(concat(function (files) {
-      callback(null, files.concat(new File({
-        path: 'index.html',
-        contents: new Buffer(pageTemplate({
-          docs: comments,
-          options: options
-        }), 'utf8')
-      })));
-    }));
+  var theme = require('documentation-theme-default');
+  if (options.theme) {
+    theme = require(path.resolve(process.cwd(), options.theme));
+  }
+  theme(comments, options, callback);
 };

lib/get_template.js

@@ -15,18 +15,15 @@
     "concat-stream": "^1.5.0",
     "debounce": "^1.0.0",
     "doctrine": "^0.7.1",
-    "documentation-theme-default": "^1.0.2",
+    "documentation-theme-default": "documentationjs/documentation-theme-default#themes-2.0",
     "events": "^1.1.0",
     "extend": "^3.0.0",
     "get-comments": "^1.0.1",
     "github-url-from-git": "^1.4.0",
-    "globals-docs": "^2.1.0",
-    "handlebars": "^3.0.0",
     "highlight.js": "^8.4.0",
     "js-yaml": "^3.3.1",
     "jsdoc-inline-lex": "^1.0.1",
     "mdast": "^2.0.0",
-    "mdast-html": "^1.2.1",
     "mdast-toc": "^1.1.0",
     "micromatch": "^2.1.6",
     "mime": "^1.3.4",
@@ -42,7 +39,6 @@
     "vfile": "^1.1.2",
     "vfile-reporter": "^1.4.1",
     "vfile-sort": "^1.0.0",
-    "vinyl": "^0.5.0",
     "vinyl-fs": "^1.0.0",
     "yargs": "^3.31.0"
   },

lib/html_helpers.js

@@ -207,6 +207,20 @@ test('write to html', function (t) {
     }, false);
 }, options);
 
+test('write to html with custom theme', function (t) {
+
+  var dstDir = path.join(os.tmpdir(), (Date.now() + Math.random()).toString());
+  fs.mkdirSync(dstDir);
+
+  documentation(['build -t fixture/custom_theme --shallow fixture/internal.input.js -f html -o ' + dstDir], {},
+    function (err, data) {
+      t.error(err);
+      t.equal(data, '');
+      t.ok(fs.readFileSync(path.join(dstDir, 'index.html'), 'utf8'), 'Hello world');
+      t.end();
+    }, false);
+}, options);
+
 test('write to html, highlightAuto', function (t) {
 
   var fixture = 'fixture/auto_lang_hljs/multilanguage.input.js',