--watch and --serve flags

These new flags replace the functionality of
dev-documentation

Author: tmcw

Diff for: bin/documentation.js

@@ -5,41 +5,76 @@
 'use strict';
 
 var documentation = require('../'),
+  chokidar = require('chokidar'),
+  debounce = require('debounce'),
   streamArray = require('stream-array'),
   fs = require('fs'),
   vfs = require('vinyl-fs'),
-  lint = require('../lib/lint'),
-  args = require('../lib/args.js');
+  errorPage = require('../lib/error_page'),
+  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];
+var parsedArgs = args(process.argv.slice(2));
 
-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 (parsedArgs.command === 'serve') {
+      return server.setFiles([errorPage(err)]).start();
+    }
     throw err;
   }
 
-  if (parsedArgs.options.lint) {
-    var lintOutput = lint.format(comments);
+  documentation.formats[parsedArgs.formatter](
+    comments, parsedArgs.formatterOptions,
+    onFormatted.bind(null, parsedArgs));
+}
+
+function onFormatted(parsedArgs, err, output) {
+  if (parsedArgs.watch) {
+    updateWatcher();
+  }
+
+  if (parsedArgs.command === 'serve') {
+    server.setFiles(output).start();
+  } else if (parsedArgs.output === 'stdout') {
+    process.stdout.write(output);
+  } else if (Array.isArray(output)) {
+    streamArray(output).pipe(vfs.dest(parsedArgs.output));
+  } else {
+    fs.writeFileSync(parsedArgs.output, output);
+  }
+}
+
+if (parsedArgs.watch) {
+  var watcher = chokidar.watch(parsedArgs.inputs);
+  watcher.on('all', debounce(generator, 300));
+} else if (parsedArgs.command === 'lint') {
+  documentation.lint(parsedArgs.inputs, parsedArgs.options, function (err, lintOutput) {
     if (lintOutput) {
       console.log(lintOutput);
       process.exit(1);
     } else {
       process.exit(0);
     }
-  }
-
-  formatter(comments, formatterOptions, function (err, output) {
-    if (outputLocation !== 'stdout') {
-      if (parsedArgs.formatter === 'html') {
-        streamArray(output).pipe(vfs.dest(outputLocation));
-      } else {
-        fs.writeFileSync(outputLocation, output);
-      }
-    } else {
-      process.stdout.write(output);
-    }
   });
-});
+} else {
+  generator();
+}
+
+function updateWatcher() {
+  documentation.expandInputs(parsedArgs.inputs, parsedArgs.options, addNewFiles);
+}
+
+function addNewFiles(err, files) {
+  watcher.add(files.map(function (data) {
+    return data.file;
+  }));
+}

Diff for: index.js

@@ -16,7 +16,8 @@ var sort = require('./lib/sort'),
   inferProperties = require('./lib/infer/properties'),
   inferMembership = require('./lib/infer/membership'),
   inferReturn = require('./lib/infer/return'),
-  lint = require('./lib/lint');
+  formatLint = require('./lib/lint').formatLint,
+  lintComments = require('./lib/lint').lintComments;
 
 /**
  * Build a pipeline of comment handlers.
@@ -45,6 +46,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,25 +90,23 @@ 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);
     }
     try {
       callback(null,
         filterAccess(
-          (options.private || options.lint) ? [] : undefined,
+          options.private ? [] : undefined,
           hierarchy(
             inputs
               .filter(filterJS)
               .reduce(function (memo, file) {
                 return memo.concat(parseFn(file));
               }, [])
               .map(pipeline(
-                lint.lint,
                 inferName(),
                 inferKind(),
                 inferParams(),
@@ -111,6 +124,65 @@ module.exports = function (indexes, options, callback) {
   });
 };
 
+/**
+ * Generate JavaScript documentation as a list of parsed JSDoc
+ * comments, given a root file as a path.
+ *
+ * @param {Array<string>|string} indexes files to process
+ * @param {Object} options options
+ * @param {Array<string>} options.external a string regex / glob match pattern
+ * that defines what external modules will be whitelisted and included in the
+ * generated documentation.
+ * @param {Array<string>} options.transform source transforms given as strings
+ * passed to [the module-deps transform option](https://github.com/substack/module-deps)
+ * @param {boolean} [options.polyglot=false] parse comments with a regex rather than
+ * a proper parser. This enables support of non-JavaScript languages but
+ * reduces documentation's ability to infer structure of code.
+ * @param {boolean} [options.shallow=false] whether to avoid dependency parsing
+ * even in JavaScript code. With the polyglot option set, this has no effect.
+ * @param {Function} callback to be called when the documentation generation
+ * is complete, with (err, result) argumentsj
+ * @returns {undefined} calls callback
+ */
+module.exports.lint = function lint(indexes, options, callback) {
+  options = options || {};
+
+  if (typeof indexes === 'string') {
+    indexes = [indexes];
+  }
+
+  var parseFn = (options.polyglot) ? polyglot : parseJavaScript;
+
+  return expandInputs(indexes, options, function (error, inputs) {
+    if (error) {
+      return callback(error);
+    }
+    try {
+      callback(null,
+        formatLint(hierarchy(
+          inputs
+            .filter(filterJS)
+            .reduce(function (memo, file) {
+              return memo.concat(parseFn(file));
+            }, [])
+            .map(pipeline(
+              lintComments,
+              inferName(),
+              inferKind(),
+              inferParams(),
+              inferProperties(),
+              inferReturn(),
+              inferMembership(),
+              nest))
+            .filter(Boolean))));
+    } catch (e) {
+      callback(e);
+    }
+  });
+};
+
+module.exports.expandInputs = expandInputs;
+
 module.exports.formats = {
   html: require('./lib/output/html'),
   md: require('./lib/output/markdown'),

Diff for: lib/args.js

@@ -8,64 +8,80 @@ function parse(args) {
   return yargs.reset()
   .usage('Usage: $0 <command> [options]')
 
-  .option('f', {
-    alias: 'format',
-    default: 'json',
-    choices: ['json', 'md', 'html']
-  })
-
-  .option('lint', {
-    describe: 'check output for common style and uniformity mistakes',
-    type: 'boolean'
-  })
+  .demand(1)
 
-  .describe('t', 'specify a theme: this must be a valid theme module')
-  .alias('t', 'theme')
-
-  .boolean('p')
-  .describe('p', 'generate documentation tagged as private')
-  .alias('p', 'private')
+  .command('build', 'build documentation')
+  .command('lint', 'check for common style and uniformity mistakes')
+  .command('serve', 'generate, update, and display HTML documentation')
 
   .version(function () {
     return require('../package').version;
   })
 
-  .describe('name', 'project name. by default, inferred from package.json')
-  .describe('project-version', 'project version. by default, inferred from package.json')
+  .help('help')
+  .alias('help', 'h')
 
+  .option('format', {
+    alias: 'f',
+    default: 'json',
+    choices: ['json', 'md', 'html']
+  })
+  .option('watch', {
+    describe: 'watch input files and rebuild documentation when they change',
+    alias: 'w',
+    type: 'boolean'
+  })
+  .option('theme', {
+    describe: 'specify a theme: this must be a valid theme module',
+    alias: 't'
+  })
+  .option('private', {
+    describe: 'generate documentation tagged as private',
+    type: 'boolean',
+    default: false,
+    alias: 'p'
+  })
+  .option('name', {
+    describe: 'project name. by default, inferred from package.json'
+  })
+  .option('project-version', {
+    describe: 'project version. by default, inferred from package.json'
+  })
   .option('shallow', {
     describe: 'shallow mode turns off dependency resolution, ' +
     'only processing the specified files (or the main script specified in package.json)',
     default: false,
     type: 'boolean'
   })
-
-  .boolean('polyglot')
-  .describe('polyglot', 'polyglot mode turns off dependency resolution and ' +
-            'enables multi-language support. use this to document c++')
-
-  .boolean('g')
-  .describe('g', 'infer links to github in documentation')
-  .alias('g', 'github')
-
-  .option('o', {
+  .option('polyglot', {
+    type: 'boolean',
+    describe: 'polyglot mode turns off dependency resolution and ' +
+      'enables multi-language support. use this to document c++'
+  })
+  .option('github', {
+    type: 'boolean',
+    describe: 'infer links to github in documentation',
+    alias: 'g'
+  })
+  .option('config', {
+    describe: 'configuration file. an array defining explicit sort order',
+    alias: 'c'
+  })
+  .option('output', {
     describe: 'output location. omit for stdout, otherwise is a filename ' +
       'for single-file outputs and a directory name for multi-file outputs like html',
-    alias: 'output',
-    default: 'stdout'
+    default: 'stdout',
+    alias: 'o'
   })
 
-  .describe('c', 'configuration file. an array defining explicit sort order')
-  .alias('c', 'config')
-
-  .help('h')
-  .alias('h', 'help')
+  .example('$0 build foo.js -f md > API.md', 'parse documentation in a ' +
+    'file and generate API documentation as Markdown')
 
-  .example('$0 foo.js', 'parse documentation in a given file')
+  .example('$0 lint project.js', 'check documentation style')
 
   .parse(args)
-
 }
+
 /**
  * Parse and validate command-line options for documentation.
  * @param {Array} args The array of arguments to parse; e.g. process.argv.slice(2).
@@ -75,14 +91,14 @@ function parse(args) {
 module.exports = function (args) {
   var argv = parse(args);
 
-  var inputs,
-    name = argv.name,
+  var command = argv._[0],
+    inputs = argv._.slice(1);
+
+  var name = argv.name,
     version = argv['project-version'],
     transform;
 
-  if (argv._.length > 0) {
-    inputs = argv._;
-  } else {
+  if (inputs.length == 0) {
     try {
       var p = require(path.resolve('package.json'));
       inputs = [p.main || 'index.js'];
@@ -97,11 +113,15 @@ module.exports = function (args) {
     }
   }
 
-  if (argv.f === 'html' && argv.o === 'stdout') {
+  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');
   }
 
+  if (command === 'serve') {
+    argv.format = 'html';
+  }
+
   var config = {};
 
   if (argv.config) {
@@ -110,16 +130,17 @@ module.exports = function (args) {
 
   return {
     inputs: inputs,
+    command: command,
     options: {
       private: argv.private,
       transform: transform,
-      lint: argv.lint,
       github: argv.github,
       polyglot: argv.polyglot,
       order: config.order || [],
       shallow: argv.shallow
     },
-    formatter: argv.f,
+    formatter: argv.format,
+    watch: argv.w,
     formatterOptions: {
       name: name,
       version: version,