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

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'),