feat(build): load passed in config option (#625)

* feat(build): load passed in config option

Fixes #documentationjs/gulp-documentation#27

* refactor(build): streamline loadConfig path

Author: dignifiedquire

index.js

@@ -24,7 +24,8 @@ var fs = require('fs'),
   formatLint = require('./lib/lint').formatLint,
   garbageCollect = require('./lib/garbage_collect'),
   lintComments = require('./lib/lint').lintComments,
-  markdownAST = require('./lib/output/markdown_ast');
+  markdownAST = require('./lib/output/markdown_ast'),
+  loadConfig = require('./lib/load_config');
 
 /**
  * Build a pipeline of comment handlers.
@@ -64,6 +65,19 @@ function expandInputs(indexes, options, callback) {
   inputFn(indexes, options, callback);
 }
 
+/**
+ * Given an options object, it expands the `config` field
+ * if it exists.
+ *
+ * @param {Object} options - options to process
+ * @returns {undefined}
+ */
+function expandConfig(options) {
+  if (options && typeof options.config === 'string') {
+    Object.assign(options, loadConfig(options.config));
+  }
+}
+
 /**
  * Generate JavaScript documentation as a list of parsed JSDoc
  * comments, given a root file as a path.
@@ -114,6 +128,8 @@ function expandInputs(indexes, options, callback) {
 function build(indexes, options, callback) {
   options = options || {};
 
+  expandConfig(options);
+
   if (typeof indexes === 'string') {
     indexes = [indexes];
   }
@@ -122,11 +138,14 @@ function build(indexes, options, callback) {
     if (error) {
       return callback(error);
     }
+
+    var result;
     try {
-      callback(null, buildSync(inputs, options));
+      result = buildSync(inputs, options);
     } catch (e) {
-      callback(e);
+      return callback(e);
     }
+    callback(null, result);
   });
 }
 
@@ -137,6 +156,7 @@ function build(indexes, options, callback) {
  *
  * @param {Array<string>} indexes files to process
  * @param {Object} options options
+ * @param {string} config path to configuration file to load
  * @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.
@@ -172,6 +192,8 @@ function buildSync(indexes, options) {
   options = options || {};
   options.hljs = options.hljs || {};
 
+  expandConfig(options);
+
   if (!options.access) {
     options.access = ['public', 'undefined', 'protected'];
   }
@@ -259,6 +281,8 @@ function buildSync(indexes, options) {
 function lint(indexes, options, callback) {
   options = options || {};
 
+  expandConfig(options);
+
   if (typeof indexes === 'string') {
     indexes = [indexes];
   }

lib/commands/build.js

@@ -49,13 +49,6 @@ module.exports.handler = function build(argv, callback) {
   if (argv.f === 'html' && argv.o === 'stdout') {
     throw new Error('The HTML output mode requires a destination directory set with -o');
   }
-  var formatterOptions = {
-    name: argv.name || (argv.package || {}).name,
-    version: argv['project-version'] || (argv.package || {}).version,
-    theme: argv.theme,
-    paths: argv.paths,
-    hljs: argv.hljs || {}
-  };
 
   var generator = documentation.build
     .bind(null, argv.input, argv, onDocumented);
@@ -68,6 +61,14 @@ module.exports.handler = function build(argv, callback) {
       throw err;
     }
 
+    var formatterOptions = {
+      name: argv.name || (argv.package || {}).name,
+      version: argv['project-version'] || (argv.package || {}).version,
+      theme: argv.theme,
+      paths: argv.paths,
+      hljs: argv.hljs || {}
+    };
+
     documentation.formats[argv.format](comments, formatterOptions, onFormatted);
   }
 

lib/commands/shared_options.js

@@ -1,5 +1,4 @@
 var path = require('path');
-var loadConfig = require('../load_config');
 
 /**
  * Adds shared options to any command that runs documentation
@@ -16,12 +15,9 @@ module.exports.sharedInputOptions = {
     type: 'boolean'
   },
   'config': {
-    config: true,
     describe: 'configuration file. an array defining explicit sort order',
     alias: 'c',
-    configParser: function (configPath) {
-      return loadConfig(configPath);
-    }
+    type: 'string'
   },
   'external': {
     describe: 'a string / glob match pattern that defines which external ' +

test/fixture/class.config.output.md

@@ -0,0 +1,29 @@
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+# MyClass
+
+This is my class, a demo thing.
+
+**Properties**
+
+-   `howMany` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** how many things it contains
+
+## getFoo
+
+Get the number 42
+
+**Parameters**
+
+-   `getIt` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** whether to get the number
+
+Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** forty-two
+
+## getUndefined
+
+Get undefined
+
+Returns **[undefined](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/undefined)** does not return anything.
+
+# Hello
+
+World

test/fixture/simple.config.yml

@@ -0,0 +1,4 @@
+toc:
+  - MyClass
+  - name: Hello
+    description: World

test/test.js

@@ -250,6 +250,22 @@ test('highlightAuto md output', function (t) {
   });
 });
 
+test('config', function (t) {
+  var file = path.join(__dirname, 'fixture', 'class.input.js');
+  var result = fs.readFileSync(path.join(__dirname, 'fixture', 'class.config.output.md')).toString();
+  documentation.build([file], {
+    config: path.join(__dirname, 'fixture', 'simple.config.yml')
+  }, function (err, out) {
+    t.ifError(err);
+    outputMarkdown(out, {}, function (err, md) {
+      t.ifError(err);
+
+      t.equal(md, result, 'rendered markdown is equal');
+      t.end();
+    });
+  });
+});
+
 test('multi-file input', function (t) {
   documentation.build([
     path.join(__dirname, 'fixture', 'simple.input.js'),