include build lib to allow direct install from this repo

Author: Alexander Droste

.gitignore

@@ -1,4 +1,4 @@
-/lib
+#/lib
 coverage
 .nyc_output
 /node_modules

lib/commands/build.js

@@ -0,0 +1,118 @@
+'use strict';
+
+const streamArray = require('stream-array');
+const sharedOptions = require('./shared_options');
+const path = require('path');
+const fs = require('fs');
+const vfs = require('vinyl-fs');
+const chokidar = require('chokidar');
+const documentation = require('../');
+const _ = require('lodash');
+
+module.exports.command = 'build [input..]';
+module.exports.describe = 'build documentation';
+
+/**
+ * Add yargs parsing for the build command
+ * @param {Object} yargs module instance
+ * @returns {Object} yargs with options
+ * @private
+ */
+module.exports.builder = Object.assign(
+  {},
+  sharedOptions.sharedOutputOptions,
+  sharedOptions.sharedInputOptions,
+  {
+    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',
+      default: 'stdout',
+      alias: 'o'
+    }
+  }
+);
+
+/*
+ * The `build` command.  Requires either `--output` or the `callback` argument.
+ * If the callback is provided, it is called with (error, formattedResult);
+ * otherwise, formatted results are outputted based on the value of `--output`.
+ *
+ * The former case, with the callback, is used by the `serve` command, which is
+ * just a thin wrapper around this one.
+ */
+module.exports.handler = function build(argv) {
+  let watcher;
+  argv._handled = true;
+
+  if (!argv.input.length) {
+    try {
+      argv.input = [
+        JSON.parse(fs.readFileSync(path.resolve('package.json'), 'utf8'))
+          .main || 'index.js'
+      ];
+    } catch (e) {
+      throw new Error(
+        'documentation was given no files and was not run in a module directory'
+      );
+    }
+  }
+
+  if (argv.f === 'html' && argv.o === 'stdout') {
+    throw new Error(
+      'The HTML output mode requires a destination directory set with -o'
+    );
+  }
+
+  function generator() {
+    return documentation
+      .build(argv.input, argv)
+      .then(comments =>
+        documentation.formats[argv.format](comments, argv).then(onFormatted)
+      )
+      .catch(err => {
+        /* eslint no-console: 0 */
+        if (err instanceof Error) {
+          console.error(err.stack);
+        } else {
+          console.error(err);
+        }
+        process.exit(1);
+      });
+  }
+
+  function onFormatted(output) {
+    if (argv.watch) {
+      updateWatcher();
+    }
+
+    if (argv.output === 'stdout') {
+      if (argv.watch) {
+        // In watch mode, clear the screen first to make updated outputs
+        // obvious.
+        process.stdout.write('\u001b[2J');
+      }
+      process.stdout.write(output);
+    } else if (Array.isArray(output)) {
+      streamArray(output).pipe(vfs.dest(argv.output));
+    } else {
+      fs.writeFileSync(argv.output, output);
+    }
+  }
+
+  function updateWatcher() {
+    if (!watcher) {
+      watcher = chokidar.watch(argv.input);
+      watcher.on('all', _.debounce(generator, 300));
+    }
+    documentation
+      .expandInputs(argv.input, argv)
+      .then(files =>
+        watcher.add(
+          files.map(data => (typeof data === 'string' ? data : data.file))
+        )
+      );
+  }
+
+  return generator();
+};

lib/commands/index.js

@@ -0,0 +1,19 @@
+'use strict';
+
+/*
+ * Maps command name to a command plugin module.  Each command plugin module
+ * must export a function that takes (documentation, parsedArgs), where
+ * documentation is just the main module (index.js), and parsedArgs is
+ * { inputs, options, command, commandOptions }
+ *
+ * Command modules should also export a `description`, which will be used in
+ * the main CLI help, and optionally a `parseArgs(yargs, parentArgv)` function
+ * to parse additional arguments.
+ */
+
+module.exports = {
+  build: require('./build'),
+  serve: require('./serve'),
+  lint: require('./lint'),
+  readme: require('./readme')
+};

lib/commands/lint.js

@@ -0,0 +1,53 @@
+'use strict';
+
+const documentation = require('../');
+const fs = require('fs');
+const path = require('path');
+const sharedOptions = require('./shared_options');
+
+/* eslint no-console: 0 */
+
+module.exports.command = 'lint [input..]';
+module.exports.description = 'check for common style and uniformity mistakes';
+module.exports.builder = {
+  shallow: sharedOptions.sharedInputOptions.shallow
+};
+
+/**
+ * Wrap around the documentation.lint method and add the additional
+ * behavior of printing to stdout and setting an exit status.
+ *
+ * @param {Object} argv cli arguments
+ * @returns {undefined} has side-effects
+ * @private
+ */
+module.exports.handler = function(argv) {
+  argv._handled = true;
+  if (!argv.input.length) {
+    try {
+      argv.input = [
+        JSON.parse(fs.readFileSync(path.resolve('package.json'), 'utf8'))
+          .main || 'index.js'
+      ];
+    } catch (e) {
+      throw new Error(
+        'documentation was given no files and was not run in a module directory'
+      );
+    }
+  }
+  documentation
+    .lint(argv.input, argv)
+    .then(lintOutput => {
+      if (lintOutput) {
+        console.log(lintOutput);
+        process.exit(1);
+      } else {
+        process.exit(0);
+      }
+    })
+    .catch(err => {
+      /* eslint no-console: 0 */
+      console.error(err);
+      process.exit(1);
+    });
+};

lib/commands/readme.js

@@ -0,0 +1,133 @@
+'use strict';
+
+const fs = require('fs');
+const remark = require('remark');
+const path = require('path');
+const documentation = require('../');
+const sharedOptions = require('./shared_options');
+const inject = require('mdast-util-inject');
+const chalk = require('chalk');
+const disparity = require('disparity');
+const getReadmeFile = require('../get-readme-file');
+
+module.exports.command = 'readme [input..]';
+module.exports.description = 'inject documentation into your README.md';
+
+const defaultReadmeFile = getReadmeFile('.');
+
+/**
+ * Add yargs parsing for the readme command
+ * @param {Object} yargs module instance
+ * @returns {Object} yargs with options
+ * @private
+ */
+module.exports.builder = Object.assign(
+  {},
+  sharedOptions.sharedOutputOptions,
+  sharedOptions.sharedInputOptions,
+  {
+    'readme-file': {
+      describe: 'The markdown file into which to inject documentation',
+      default: defaultReadmeFile
+    },
+    section: {
+      alias: 's',
+      describe:
+        'The section heading after which to inject generated documentation',
+      required: true
+    },
+    'diff-only': {
+      alias: 'd',
+      describe:
+        'Instead of updating the given README with the generated documentation,' +
+        ' just check if its contents match, exiting nonzero if not.',
+      default: false
+    },
+    quiet: {
+      alias: 'q',
+      describe: 'Quiet mode: do not print messages or README diff to stdout.',
+      default: false
+    }
+  }
+);
+
+/**
+ * Insert API documentation into a Markdown readme
+ * @private
+ * @param {Object} argv args from the CLI option parser
+ * @returns {undefined} has the side-effect of writing a file or printing to stdout
+ */
+module.exports.handler = function readme(argv) {
+  argv._handled = true;
+
+  if (!argv.input.length) {
+    try {
+      argv.input = [
+        JSON.parse(fs.readFileSync(path.resolve('package.json'), 'utf8'))
+          .main || 'index.js'
+      ];
+    } catch (e) {
+      throw new Error(
+        'documentation was given no files and was not run in a module directory'
+      );
+    }
+  }
+
+  argv.noReferenceLinks = true;
+  argv.format = 'remark';
+  /* eslint no-console: 0 */
+  const log = (...data) => {
+    if (!argv.q) {
+      console.log.apply(console, data);
+    }
+  };
+
+  const readmeContent = fs.readFileSync(argv.readmeFile, 'utf8');
+
+  documentation
+    .build(argv.input, argv)
+    .then(comments => documentation.formats.remark(comments, argv))
+    .then(docsAst =>
+      remark()
+        .use(plugin, {
+          section: argv.section,
+          toInject: JSON.parse(docsAst)
+        })
+        .process(readmeContent)
+    )
+    .then(file => {
+      const diffOutput = disparity.unified(readmeContent, file.contents, {
+        paths: [argv.readmeFile, argv.readmeFile]
+      });
+      if (!diffOutput.length) {
+        log(`${argv.readmeFile} is up to date.`);
+        process.exit(0);
+      }
+
+      if (argv.d) {
+        log(
+          chalk.bold(`${argv.readmeFile} needs the following updates:`),
+          `\n${diffOutput}`
+        );
+        process.exit(1);
+      } else {
+        log(chalk.bold(`Updating ${argv.readmeFile}`), `\n${diffOutput}`);
+      }
+
+      fs.writeFileSync(argv.readmeFile, file.contents);
+    })
+    .catch(err => {
+      console.error(err);
+      process.exit(1);
+    });
+};
+
+// wrap the inject utility as an remark plugin
+function plugin(options) {
+  return function transform(targetAst, file, next) {
+    if (!inject(options.section, targetAst, options.toInject)) {
+      return next(new Error(`Heading ${options.section} not found.`));
+    }
+    next();
+  };
+}