--watch and --serve flags

These new flags replace the functionality of
dev-documentation

Author: tmcw

Diff for: bin/documentation.js

@@ -5,19 +5,32 @@
 'use strict';
 
 var documentation = require('../'),
+  chokidar = require('chokidar'),
+  debounce = require('debounce'),
   streamArray = require('stream-array'),
   fs = require('fs'),
   vfs = require('vinyl-fs'),
+  errorPage = require('../lib/error_page'),
   lint = require('../lib/lint'),
-  args = require('../lib/args.js');
+  Server = require('../lib/server'),
+  args = require('../lib/args');
 
 var parsedArgs = args(process.argv.slice(2)),
-  formatterOptions = parsedArgs.formatterOptions,
-  outputLocation = parsedArgs.output,
-  formatter = documentation.formats[parsedArgs.formatter];
+  servingHTML = parsedArgs.serve && parsedArgs.formatter === 'html';
 
-documentation(parsedArgs.inputs, parsedArgs.options, function (err, comments) {
+var generator = documentation.bind(null,
+  parsedArgs.inputs, parsedArgs.options, onDocumented.bind(null, parsedArgs));
+
+var server = new Server();
+server.on('listening', function () {
+  process.stdout.write('documentation.js serving on port 4001\n');
+});
+
+function onDocumented(parsedArgs, err, comments) {
   if (err) {
+    if (servingHTML) {
+      return server.setFiles([errorPage(err)]).start();
+    }
     throw err;
   }
 
@@ -31,15 +44,42 @@ documentation(parsedArgs.inputs, parsedArgs.options, function (err, comments) {
     }
   }
 
-  formatter(comments, formatterOptions, function (err, output) {
-    if (outputLocation !== 'stdout') {
-      if (parsedArgs.formatter === 'html') {
-        streamArray(output).pipe(vfs.dest(outputLocation));
-      } else {
-        fs.writeFileSync(outputLocation, output);
-      }
+  documentation.formats[parsedArgs.formatter](
+    comments, parsedArgs.formatterOptions,
+    onFormatted.bind(null, parsedArgs));
+}
+
+function onFormatted(parsedArgs, err, output) {
+  var destination = parsedArgs.output;
+  if (destination !== 'stdout') {
+    if (parsedArgs.formatter === 'html') {
+      streamArray(output)
+        .pipe(vfs.dest(destination));
     } else {
-      process.stdout.write(output);
+      fs.writeFileSync(destination, output);
     }
+  } else if (parsedArgs.formatter !== 'html') {
+    process.stdout.write(output);
+  }
+  if (parsedArgs.formatter === 'html' && parsedArgs.serve) {
+    server.setFiles(output).start();
+  }
+  if (parsedArgs.watch) {
+    updateWatcher();
+  }
+}
+
+if (parsedArgs.watch) {
+  var watcher = chokidar.watch(parsedArgs.inputs);
+  watcher.on('all', debounce(generator, 300));
+} else {
+  generator();
+}
+
+function updateWatcher() {
+  documentation.expandInputs(parsedArgs.inputs, parsedArgs.options, function (err, files) {
+    watcher.add(files.map(function (data) {
+      return data.file;
+    }));
   });
-});
+}

Diff for: index.js

@@ -45,6 +45,20 @@ function noop(comment) {
   return comment;
 }
 
+/**
+ * Given an array of indexes and options for whether to resolve shallow
+ * or deep dependencies, resolve dependencies.
+ *
+ * @param {Array<string>|string} indexes files to process
+ * @param {Object} options options
+ * @param {Function} callback called with results
+ * @returns {undefined}
+ */
+function expandInputs(indexes, options, callback) {
+  var inputFn = (options.polyglot || options.shallow) ? shallow : dependency;
+  inputFn(indexes, options, callback);
+}
+
 /**
  * Generate JavaScript documentation as a list of parsed JSDoc
  * comments, given a root file as a path.
@@ -75,10 +89,9 @@ module.exports = function (indexes, options, callback) {
     indexes = [indexes];
   }
 
-  var inputFn = (options.polyglot || options.shallow) ? shallow : dependency;
   var parseFn = (options.polyglot) ? polyglot : parseJavaScript;
 
-  return inputFn(indexes, options, function (error, inputs) {
+  return expandInputs(indexes, options, function (error, inputs) {
     if (error) {
       return callback(error);
     }
@@ -111,6 +124,8 @@ module.exports = function (indexes, options, callback) {
   });
 };
 
+module.exports.expandInputs = expandInputs;
+
 module.exports.formats = {
   html: require('./lib/output/html'),
   md: require('./lib/output/markdown'),

Diff for: lib/args.js

@@ -19,6 +19,18 @@ function parse(args) {
     type: 'boolean'
   })
 
+  .option('w', {
+    describe: 'watch input files and rebuild documentation when they change',
+    alias: 'watch',
+    type: 'boolean'
+  })
+
+  .option('s', {
+    describe: 'serve html files under a webserver. must be used alongide -w',
+    alias: 'serve',
+    type: 'boolean'
+  })
+
   .describe('t', 'specify a theme: this must be a valid theme module')
   .alias('t', 'theme')
 
@@ -97,7 +109,12 @@ module.exports = function (args) {
     }
   }
 
-  if (argv.f === 'html' && argv.o === 'stdout') {
+  if (argv.w && argv.lint) {
+    yargs.showHelp();
+    throw new Error('--lint cannot be specified along with --watch');
+  }
+
+  if (argv.f === 'html' && argv.o === 'stdout' && !argv.serve) {
     yargs.showHelp();
     throw new Error('The HTML output mode requires a destination directory set with -o');
   }
@@ -120,6 +137,8 @@ module.exports = function (args) {
       shallow: argv.shallow
     },
     formatter: argv.f,
+    watch: argv.w,
+    serve: argv.s,
     formatterOptions: {
       name: name,
       version: version,

Diff for: lib/error_page.js

@@ -0,0 +1,25 @@
+var File = require('vinyl');
+var ansiHTML = require('ansi-html');
+
+var template = '<head><style>' +
+  'body{padding:20px;font:16px monospace;background:#CC0000;color:#fff;}' +
+  'pre{background:#fff}' +
+  '</style></head>';
+
+/**
+ * Given an error, generate an HTML page that represents the error.
+ * @param {Error} error parse or generation error
+ * @returns {Object} vinyl file object
+ */
+function errorPage(error) {
+  var errorText = error.toString();
+  if (error.codeFrame) {
+    errorText += '<pre>' + ansiHTML(error.codeFrame) + '</pre>';
+  }
+  return new File({
+    path: 'index.html',
+    contents: new Buffer(template + errorText)
+  });
+}
+
+module.exports = errorPage;

Diff for: lib/server.js

@@ -0,0 +1,105 @@
+var http = require('http'),
+  mime = require('mime'),
+  util = require('util'),
+  EventEmitter = require('events').EventEmitter,
+  liveReload = require('tiny-lr');
+
+/**
+ * A static file server designed to support documentation.js's --serve
+ * option. It serves from an array of Vinyl File objects (virtual files in
+ * memory) and exposes a `setFiles` method that both replaces the set
+ * of files and notifies any browsers using LiveReload to reload
+ * and display the new content.
+ * @class
+ */
+function Server() {
+  this._files = [];
+}
+
+util.inherits(Server, EventEmitter);
+
+/**
+ * Update the set of files exposed by this server and notify LiveReload
+ * clients
+ *
+ * @param {Array<File>} files new content. replaces any previously-set content.
+ * @returns {Server} self
+ */
+Server.prototype.setFiles = function (files) {
+  this._files = files;
+  if (this._lr) {
+    this._lr.changed({ body: { files: '*' } });
+  }
+  return this;
+};
+
+Server.prototype.handler = function (request, response) {
+  var path = request.url.substring(1);
+  if (path === '') {
+    path = 'index.html';
+  }
+  for (var i = 0; i < this._files.length; i++) {
+    if (this._files[i].relative === path) {
+      response.writeHead(200, { 'Content-Type': mime.lookup(path) });
+      this._files[i].pipe(response);
+      return;
+    }
+  }
+  response.writeHead(404, { 'Content-Type': 'text/plain' });
+  response.end('Not found');
+};
+
+/**
+ * Boot up the server's HTTP & LiveReload endpoints. This method
+ * can be called multiple times.
+ *
+ * @param {Function} [callback=] called when server is started
+ * @returns {undefined}
+ */
+Server.prototype.start = function (callback) {
+
+  callback = callback || noop;
+
+  // idempotent
+  if (this._lr) {
+    return callback();
+  }
+
+  this._lr = liveReload();
+  this._http = http.createServer(this.handler.bind(this));
+
+  this._lr.listen(35729, function () {
+    this._http.listen(4001, function () {
+      this.emit('listening');
+      callback();
+    }.bind(this));
+  }.bind(this));
+};
+
+/**
+ * Shut down the server's HTTP & LiveReload endpoints. This method
+ * can be called multiple times.
+ *
+ * @param {Function} [callback=] called when server is closed
+ * @returns {undefined}
+ */
+Server.prototype.stop = function (callback) {
+
+  callback = callback || noop;
+
+  // idempotent
+  if (!this._lr) {
+    return callback();
+  }
+
+  this._http.close(function () {
+    this._lr.close();
+    this._http = null;
+    this._lr = null;
+    callback();
+  }.bind(this));
+};
+
+function noop() {}
+
+module.exports = Server;

Diff for: package.json

@@ -15,13 +15,17 @@
     "vinyl-fs": false
   },
   "dependencies": {
+    "ansi-html": "0.0.4",
     "ast-types": "^0.8.12",
-    "babelify": "^6.3.0",
     "babel-core": "^5.0.0",
+    "babelify": "^6.3.0",
     "brfs": "^1.4.0",
+    "chokidar": "^1.2.0",
     "concat-stream": "^1.5.0",
+    "debounce": "^1.0.0",
     "doctrine": "^0.7.1",
     "documentation-theme-default": "^1.0.0",
+    "events": "^1.1.0",
     "extend": "^3.0.0",
     "get-comments": "^1.0.1",
     "github-url-from-git": "^1.4.0",
@@ -34,13 +38,15 @@
     "mdast-html": "^1.2.1",
     "mdast-toc": "^1.1.0",
     "micromatch": "^2.1.6",
+    "mime": "^1.3.4",
     "module-deps": "^3.7.3",
     "parse-filepath": "^0.6.3",
     "remote-origin-url": "^0.4.0",
     "resolve": "^1.1.6",
     "slugg": "^0.1.2",
     "stream-array": "^1.1.0",
     "strip-json-comments": "^1.0.2",
+    "tiny-lr": "^0.2.1",
     "traverse": "^0.6.6",
     "unist-builder": "^1.0.0",
     "vfile": "^1.1.2",