466 lines
13 KiB
JavaScript
466 lines
13 KiB
JavaScript
|
/* eslint-disable indent, no-process-exit */
|
||
|
|
/**
|
||
|
|
* Helper methods for running JSDoc on the command line.
|
||
|
|
*
|
||
|
|
* A few critical notes for anyone who works on this module:
|
||
|
|
*
|
||
|
|
* + The module should really export an instance of `cli`, and `props` should be properties of a
|
||
|
|
* `cli` instance.
|
||
|
|
*
|
||
|
|
* @private
|
||
|
|
*/
|
||
|
|
module.exports = (() => {
|
||
|
|
const app = require('jsdoc/app');
|
||
|
|
const env = require('jsdoc/env');
|
||
|
|
const logger = require('jsdoc/util/logger');
|
||
|
|
const stripBom = require('jsdoc/util/stripbom');
|
||
|
|
const stripJsonComments = require('strip-json-comments');
|
||
|
|
const Promise = require('bluebird');
|
||
|
|
|
||
|
|
const props = {
|
||
|
|
docs: [],
|
||
|
|
packageJson: null,
|
||
|
|
shouldExitWithError: false,
|
||
|
|
tmpdir: null
|
||
|
|
};
|
||
|
|
|
||
|
|
const FATAL_ERROR_MESSAGE = 'Exiting JSDoc because an error occurred. See the previous log ' +
|
||
|
|
'messages for details.';
|
||
|
|
const cli = {};
|
||
|
|
|
||
|
|
// TODO: docs
|
||
|
|
cli.setVersionInfo = () => {
|
||
|
|
const fs = require('fs');
|
||
|
|
const path = require('path');
|
||
|
|
|
||
|
|
// allow this to throw--something is really wrong if we can't read our own package file
|
||
|
|
const info = JSON.parse( stripBom.strip(fs.readFileSync(path.join(env.dirname, 'package.json'),
|
||
|
|
'utf8')) );
|
||
|
|
|
||
|
|
env.version = {
|
||
|
|
number: info.version,
|
||
|
|
revision: new Date( parseInt(info.revision, 10) ).toUTCString()
|
||
|
|
};
|
||
|
|
|
||
|
|
return cli;
|
||
|
|
};
|
||
|
|
|
||
|
|
// TODO: docs
|
||
|
|
cli.loadConfig = () => {
|
||
|
|
const _ = require('underscore');
|
||
|
|
const args = require('jsdoc/opts/args');
|
||
|
|
const Config = require('jsdoc/config');
|
||
|
|
let config;
|
||
|
|
const fs = require('jsdoc/fs');
|
||
|
|
const path = require('jsdoc/path');
|
||
|
|
|
||
|
|
let confPath;
|
||
|
|
let isFile;
|
||
|
|
|
||
|
|
const defaultOpts = {
|
||
|
|
destination: './out/',
|
||
|
|
encoding: 'utf8'
|
||
|
|
};
|
||
|
|
|
||
|
|
try {
|
||
|
|
env.opts = args.parse(env.args);
|
||
|
|
}
|
||
|
|
catch (e) {
|
||
|
|
console.error(`${e.message}\n`);
|
||
|
|
cli.printHelp().then(() => {
|
||
|
|
cli.exit(1);
|
||
|
|
});
|
||
|
|
}
|
||
|
|
|
||
|
|
confPath = env.opts.configure || path.join(env.dirname, 'conf.json');
|
||
|
|
try {
|
||
|
|
isFile = fs.statSync(confPath).isFile();
|
||
|
|
}
|
||
|
|
catch (e) {
|
||
|
|
isFile = false;
|
||
|
|
}
|
||
|
|
|
||
|
|
if ( !isFile && !env.opts.configure ) {
|
||
|
|
confPath = path.join(env.dirname, 'conf.json.EXAMPLE');
|
||
|
|
}
|
||
|
|
|
||
|
|
try {
|
||
|
|
switch ( path.extname(confPath) ) {
|
||
|
|
case '.js':
|
||
|
|
config = require( path.resolve(confPath) ) || {};
|
||
|
|
break;
|
||
|
|
case '.json':
|
||
|
|
case '.EXAMPLE':
|
||
|
|
default:
|
||
|
|
config = fs.readFileSync(confPath, 'utf8');
|
||
|
|
break;
|
||
|
|
}
|
||
|
|
env.conf = new Config(config).get();
|
||
|
|
}
|
||
|
|
catch (e) {
|
||
|
|
cli.exit(1, `Cannot parse the config file ${confPath}: ${e}\n${FATAL_ERROR_MESSAGE}`);
|
||
|
|
}
|
||
|
|
|
||
|
|
// look for options on the command line, in the config file, and in the defaults, in that order
|
||
|
|
env.opts = _.defaults(env.opts, env.conf.opts, defaultOpts);
|
||
|
|
|
||
|
|
return cli;
|
||
|
|
};
|
||
|
|
|
||
|
|
// TODO: docs
|
||
|
|
cli.configureLogger = () => {
|
||
|
|
function recoverableError() {
|
||
|
|
props.shouldExitWithError = true;
|
||
|
|
}
|
||
|
|
|
||
|
|
function fatalError() {
|
||
|
|
cli.exit(1);
|
||
|
|
}
|
||
|
|
|
||
|
|
if (env.opts.debug) {
|
||
|
|
logger.setLevel(logger.LEVELS.DEBUG);
|
||
|
|
}
|
||
|
|
else if (env.opts.verbose) {
|
||
|
|
logger.setLevel(logger.LEVELS.INFO);
|
||
|
|
}
|
||
|
|
|
||
|
|
if (env.opts.pedantic) {
|
||
|
|
logger.once('logger:warn', recoverableError);
|
||
|
|
logger.once('logger:error', fatalError);
|
||
|
|
}
|
||
|
|
else {
|
||
|
|
logger.once('logger:error', recoverableError);
|
||
|
|
}
|
||
|
|
|
||
|
|
logger.once('logger:fatal', fatalError);
|
||
|
|
|
||
|
|
return cli;
|
||
|
|
};
|
||
|
|
|
||
|
|
// TODO: docs
|
||
|
|
cli.logStart = () => {
|
||
|
|
logger.debug( cli.getVersion() );
|
||
|
|
|
||
|
|
logger.debug('Environment info: %j', {
|
||
|
|
env: {
|
||
|
|
conf: env.conf,
|
||
|
|
opts: env.opts
|
||
|
|
}
|
||
|
|
});
|
||
|
|
};
|
||
|
|
|
||
|
|
// TODO: docs
|
||
|
|
cli.logFinish = () => {
|
||
|
|
let delta;
|
||
|
|
let deltaSeconds;
|
||
|
|
|
||
|
|
if (env.run.finish && env.run.start) {
|
||
|
|
delta = env.run.finish.getTime() - env.run.start.getTime();
|
||
|
|
}
|
||
|
|
|
||
|
|
if (delta !== undefined) {
|
||
|
|
deltaSeconds = (delta / 1000).toFixed(2);
|
||
|
|
logger.info('Finished running in %s seconds.', deltaSeconds);
|
||
|
|
}
|
||
|
|
};
|
||
|
|
|
||
|
|
// TODO: docs
|
||
|
|
cli.runCommand = cb => {
|
||
|
|
let cmd;
|
||
|
|
|
||
|
|
const opts = env.opts;
|
||
|
|
|
||
|
|
if (opts.help) {
|
||
|
|
cmd = cli.printHelp;
|
||
|
|
}
|
||
|
|
else if (opts.test) {
|
||
|
|
cmd = cli.runTests;
|
||
|
|
}
|
||
|
|
else if (opts.version) {
|
||
|
|
cmd = cli.printVersion;
|
||
|
|
}
|
||
|
|
else {
|
||
|
|
cmd = cli.main;
|
||
|
|
}
|
||
|
|
|
||
|
|
cmd().then(errorCode => {
|
||
|
|
if (!errorCode && props.shouldExitWithError) {
|
||
|
|
errorCode = 1;
|
||
|
|
}
|
||
|
|
cb(errorCode);
|
||
|
|
});
|
||
|
|
};
|
||
|
|
|
||
|
|
// TODO: docs
|
||
|
|
cli.printHelp = () => {
|
||
|
|
cli.printVersion();
|
||
|
|
console.log( `\n${require('jsdoc/opts/args').help()}\n` );
|
||
|
|
console.log('Visit https://jsdoc.app/ for more information.');
|
||
|
|
|
||
|
|
return Promise.resolve(0);
|
||
|
|
};
|
||
|
|
|
||
|
|
// TODO: docs
|
||
|
|
cli.runTests = () => {
|
||
|
|
const path = require('jsdoc/path');
|
||
|
|
|
||
|
|
const runner = Promise.promisify(require( path.join(env.dirname, 'test/runner') ));
|
||
|
|
|
||
|
|
console.log('Running tests...');
|
||
|
|
|
||
|
|
return runner();
|
||
|
|
};
|
||
|
|
|
||
|
|
// TODO: docs
|
||
|
|
cli.getVersion = () => `JSDoc ${env.version.number} (${env.version.revision})`;
|
||
|
|
|
||
|
|
// TODO: docs
|
||
|
|
cli.printVersion = () => {
|
||
|
|
console.log( cli.getVersion() );
|
||
|
|
|
||
|
|
return Promise.resolve(0);
|
||
|
|
};
|
||
|
|
|
||
|
|
// TODO: docs
|
||
|
|
cli.main = () => {
|
||
|
|
cli.scanFiles();
|
||
|
|
|
||
|
|
if (env.sourceFiles.length === 0) {
|
||
|
|
console.log('There are no input files to process.');
|
||
|
|
|
||
|
|
return Promise.resolve(0);
|
||
|
|
} else {
|
||
|
|
return cli.createParser()
|
||
|
|
.parseFiles()
|
||
|
|
.processParseResults()
|
||
|
|
.then(() => {
|
||
|
|
env.run.finish = new Date();
|
||
|
|
|
||
|
|
return 0;
|
||
|
|
});
|
||
|
|
}
|
||
|
|
};
|
||
|
|
|
||
|
|
function readPackageJson(filepath) {
|
||
|
|
const fs = require('jsdoc/fs');
|
||
|
|
|
||
|
|
try {
|
||
|
|
return stripJsonComments( fs.readFileSync(filepath, 'utf8') );
|
||
|
|
}
|
||
|
|
catch (e) {
|
||
|
|
logger.error('Unable to read the package file "%s"', filepath);
|
||
|
|
|
||
|
|
return null;
|
||
|
|
}
|
||
|
|
}
|
||
|
|
|
||
|
|
function buildSourceList() {
|
||
|
|
const Readme = require('jsdoc/readme');
|
||
|
|
|
||
|
|
let packageJson;
|
||
|
|
let readmeHtml;
|
||
|
|
let sourceFile;
|
||
|
|
let sourceFiles = env.opts._ ? env.opts._.slice(0) : [];
|
||
|
|
|
||
|
|
if (env.conf.source && env.conf.source.include) {
|
||
|
|
sourceFiles = sourceFiles.concat(env.conf.source.include);
|
||
|
|
}
|
||
|
|
|
||
|
|
// load the user-specified package/README files, if any
|
||
|
|
if (env.opts.package) {
|
||
|
|
packageJson = readPackageJson(env.opts.package);
|
||
|
|
}
|
||
|
|
if (env.opts.readme) {
|
||
|
|
readmeHtml = new Readme(env.opts.readme).html;
|
||
|
|
}
|
||
|
|
|
||
|
|
// source files named `package.json` or `README.md` get special treatment, unless the user
|
||
|
|
// explicitly specified a package and/or README file
|
||
|
|
for (let i = 0, l = sourceFiles.length; i < l; i++) {
|
||
|
|
sourceFile = sourceFiles[i];
|
||
|
|
|
||
|
|
if ( !env.opts.package && /\bpackage\.json$/i.test(sourceFile) ) {
|
||
|
|
packageJson = readPackageJson(sourceFile);
|
||
|
|
sourceFiles.splice(i--, 1);
|
||
|
|
}
|
||
|
|
|
||
|
|
if ( !env.opts.readme && /(\bREADME|\.md)$/i.test(sourceFile) ) {
|
||
|
|
readmeHtml = new Readme(sourceFile).html;
|
||
|
|
sourceFiles.splice(i--, 1);
|
||
|
|
}
|
||
|
|
}
|
||
|
|
|
||
|
|
props.packageJson = packageJson;
|
||
|
|
env.opts.readme = readmeHtml;
|
||
|
|
|
||
|
|
return sourceFiles;
|
||
|
|
}
|
||
|
|
|
||
|
|
// TODO: docs
|
||
|
|
cli.scanFiles = () => {
|
||
|
|
const Filter = require('jsdoc/src/filter').Filter;
|
||
|
|
|
||
|
|
let filter;
|
||
|
|
|
||
|
|
env.opts._ = buildSourceList();
|
||
|
|
|
||
|
|
// are there any files to scan and parse?
|
||
|
|
if (env.conf.source && env.opts._.length) {
|
||
|
|
filter = new Filter(env.conf.source);
|
||
|
|
|
||
|
|
env.sourceFiles = app.jsdoc.scanner.scan(env.opts._,
|
||
|
|
(env.opts.recurse ? env.conf.recurseDepth : undefined), filter);
|
||
|
|
}
|
||
|
|
|
||
|
|
return cli;
|
||
|
|
};
|
||
|
|
|
||
|
|
function resolvePluginPaths(paths) {
|
||
|
|
const path = require('jsdoc/path');
|
||
|
|
|
||
|
|
const pluginPaths = [];
|
||
|
|
|
||
|
|
paths.forEach(plugin => {
|
||
|
|
const basename = path.basename(plugin);
|
||
|
|
const dirname = path.dirname(plugin);
|
||
|
|
const pluginPath = path.getResourcePath(dirname, basename);
|
||
|
|
|
||
|
|
if (!pluginPath) {
|
||
|
|
logger.error('Unable to find the plugin "%s"', plugin);
|
||
|
|
|
||
|
|
return;
|
||
|
|
}
|
||
|
|
|
||
|
|
pluginPaths.push( pluginPath );
|
||
|
|
});
|
||
|
|
|
||
|
|
return pluginPaths;
|
||
|
|
}
|
||
|
|
|
||
|
|
cli.createParser = () => {
|
||
|
|
const handlers = require('jsdoc/src/handlers');
|
||
|
|
const parser = require('jsdoc/src/parser');
|
||
|
|
const plugins = require('jsdoc/plugins');
|
||
|
|
|
||
|
|
app.jsdoc.parser = parser.createParser(env.conf.parser);
|
||
|
|
|
||
|
|
if (env.conf.plugins) {
|
||
|
|
env.conf.plugins = resolvePluginPaths(env.conf.plugins);
|
||
|
|
plugins.installPlugins(env.conf.plugins, app.jsdoc.parser);
|
||
|
|
}
|
||
|
|
|
||
|
|
handlers.attachTo(app.jsdoc.parser);
|
||
|
|
|
||
|
|
return cli;
|
||
|
|
};
|
||
|
|
|
||
|
|
cli.parseFiles = () => {
|
||
|
|
const augment = require('jsdoc/augment');
|
||
|
|
const borrow = require('jsdoc/borrow');
|
||
|
|
const Package = require('jsdoc/package').Package;
|
||
|
|
|
||
|
|
let docs;
|
||
|
|
let packageDocs;
|
||
|
|
|
||
|
|
props.docs = docs = app.jsdoc.parser.parse(env.sourceFiles, env.opts.encoding);
|
||
|
|
|
||
|
|
// If there is no package.json, just create an empty package
|
||
|
|
packageDocs = new Package(props.packageJson);
|
||
|
|
packageDocs.files = env.sourceFiles || [];
|
||
|
|
docs.push(packageDocs);
|
||
|
|
|
||
|
|
logger.debug('Adding inherited symbols, mixins, and interface implementations...');
|
||
|
|
augment.augmentAll(docs);
|
||
|
|
logger.debug('Adding borrowed doclets...');
|
||
|
|
borrow.resolveBorrows(docs);
|
||
|
|
logger.debug('Post-processing complete.');
|
||
|
|
|
||
|
|
app.jsdoc.parser.fireProcessingComplete(docs);
|
||
|
|
|
||
|
|
return cli;
|
||
|
|
};
|
||
|
|
|
||
|
|
cli.processParseResults = () => {
|
||
|
|
if (env.opts.explain) {
|
||
|
|
cli.dumpParseResults();
|
||
|
|
|
||
|
|
return Promise.resolve();
|
||
|
|
}
|
||
|
|
else {
|
||
|
|
cli.resolveTutorials();
|
||
|
|
|
||
|
|
return cli.generateDocs();
|
||
|
|
}
|
||
|
|
};
|
||
|
|
|
||
|
|
cli.dumpParseResults = () => {
|
||
|
|
console.log(require('jsdoc/util/dumper').dump(props.docs));
|
||
|
|
|
||
|
|
return cli;
|
||
|
|
};
|
||
|
|
|
||
|
|
cli.resolveTutorials = () => {
|
||
|
|
const resolver = require('jsdoc/tutorial/resolver');
|
||
|
|
|
||
|
|
if (env.opts.tutorials) {
|
||
|
|
resolver.load(env.opts.tutorials);
|
||
|
|
resolver.resolve();
|
||
|
|
}
|
||
|
|
|
||
|
|
return cli;
|
||
|
|
};
|
||
|
|
|
||
|
|
cli.generateDocs = () => {
|
||
|
|
const path = require('jsdoc/path');
|
||
|
|
const resolver = require('jsdoc/tutorial/resolver');
|
||
|
|
const taffy = require('taffydb').taffy;
|
||
|
|
|
||
|
|
let template;
|
||
|
|
|
||
|
|
env.opts.template = (() => {
|
||
|
|
const publish = env.opts.template || 'templates/default';
|
||
|
|
const templatePath = path.getResourcePath(publish);
|
||
|
|
|
||
|
|
// if we didn't find the template, keep the user-specified value so the error message is
|
||
|
|
// useful
|
||
|
|
return templatePath || env.opts.template;
|
||
|
|
})();
|
||
|
|
|
||
|
|
try {
|
||
|
|
template = require(`${env.opts.template}/publish`);
|
||
|
|
}
|
||
|
|
catch (e) {
|
||
|
|
logger.fatal(`Unable to load template: ${e.message}` || e);
|
||
|
|
}
|
||
|
|
|
||
|
|
// templates should include a publish.js file that exports a "publish" function
|
||
|
|
if (template.publish && typeof template.publish === 'function') {
|
||
|
|
let publishPromise;
|
||
|
|
|
||
|
|
logger.info('Generating output files...');
|
||
|
|
publishPromise = template.publish(
|
||
|
|
taffy(props.docs),
|
||
|
|
env.opts,
|
||
|
|
resolver.root
|
||
|
|
);
|
||
|
|
|
||
|
|
return Promise.resolve(publishPromise);
|
||
|
|
}
|
||
|
|
else {
|
||
|
|
logger.fatal(`${env.opts.template} does not export a "publish" function. Global "publish" functions are no longer supported.`);
|
||
|
|
}
|
||
|
|
|
||
|
|
return Promise.resolve();
|
||
|
|
};
|
||
|
|
|
||
|
|
// TODO: docs
|
||
|
|
cli.exit = (exitCode, message) => {
|
||
|
|
if (exitCode > 0 && message) {
|
||
|
|
console.error(message);
|
||
|
|
}
|
||
|
|
process.on('exit', () => { process.exit(exitCode); });
|
||
|
|
};
|
||
|
|
|
||
|
|
return cli;
|
||
|
|
})();
|