@ui5/builder/lib/processors/jsdoc/jsdocGenerator.js

UI5 Tooling - Builder

const spawn = require("child_process").spawn;
const fs = require("graceful-fs");
const path = require("path");
const {promisify} = require("util");
const writeFile = promisify(fs.writeFile);
const {resourceFactory} = require("@ui5/fs");

/**
 * JSDoc generator
 *
 * @public
 * @alias module:@ui5/builder.processors.jsdocGenerator
 * @param {Object} parameters Parameters
 * @param {string} parameters.sourcePath Path of the source files to be processed
 * @param {string} parameters.targetPath Path to write any output files
 * @param {string} parameters.tmpPath Path to write temporary and debug files
 * @param {Object} parameters.options Options
 * @param {string} parameters.options.projectName Project name
 * @param {string} parameters.options.namespace Namespace to build (e.g. <code>some/project/name</code>)
 * @param {string} parameters.options.version Project version
 * @param {Array} [parameters.options.variants=["apijson"]] JSDoc variants to be built
 * @returns {Promise<module:@ui5/fs.Resource[]>} Promise resolving with newly created resources
 */
const jsdocGenerator = async function({sourcePath, targetPath, tmpPath, options} = {}) {
	if (!sourcePath || !targetPath || !tmpPath || !options.projectName || !options.namespace || !options.version) {
		throw new Error("[jsdocGenerator]: One or more mandatory parameters not provided");
	}

	if (!options.variants || options.variants.length === 0) {
		options.variants = ["apijson"];
	}

	const config = await jsdocGenerator._generateJsdocConfig({
		targetPath,
		tmpPath,
		namespace: options.namespace,
		projectName: options.projectName,
		version: options.version,
		variants: options.variants
	});

	const configPath = await jsdocGenerator._writeJsdocConfig(tmpPath, config);

	await jsdocGenerator._buildJsdoc({
		sourcePath,
		configPath
	});

	const fsTarget = resourceFactory.createAdapter({
		fsBasePath: targetPath,
		virBasePath: "/"
	});

	// create resources from the output files
	return Promise.all([
		fsTarget.byPath(`/test-resources/${options.namespace}/designtime/api.json`)
		// fsTarget.byPath(`/libraries/${options.projectName}.js`)
	]).then((res) => res.filter(($)=>$));
};


/**
 * Generate jsdoc-config.json content
 *
 * @private
 * @param {Object} parameters Parameters
 * @param {string} parameters.targetPath Path to write any output files
 * @param {string} parameters.tmpPath Path to write temporary and debug files
 * @param {string} parameters.projectName Project name
 * @param {string} parameters.version Project version
 * @param {Array} parameters.variants JSDoc variants to be built
 * @returns {string} jsdoc-config.json content string
 */
async function generateJsdocConfig({targetPath, tmpPath, namespace, projectName, version, variants}) {
	// Backlash needs to be escaped as double-backslash
	// This is not only relevant for win32 paths but also for
	//	Unix directory names that contain a backslash in their name
	const backslashRegex = /\\/g;

	// Resolve path to this script to get the path to the JSDoc extensions folder
	const jsdocPath = path.normalize(__dirname);
	const pluginPath = path.join(jsdocPath, "lib", "ui5", "plugin.js").replace(backslashRegex, "\\\\");
	const templatePath = path.join(jsdocPath, "lib", "ui5", "template").replace(backslashRegex, "\\\\");
	const destinationPath = path.normalize(tmpPath).replace(backslashRegex, "\\\\");
	const jsapiFilePath = path.join(targetPath, "libraries", projectName + ".js").replace(backslashRegex, "\\\\");
	const apiJsonFolderPath = path.join(tmpPath, "dependency-apis").replace(backslashRegex, "\\\\");
	const apiJsonFilePath =
		path.join(targetPath, "test-resources", path.normalize(namespace), "designtime", "api.json")
			.replace(backslashRegex, "\\\\");

	const config = `{
		"plugins": ["${pluginPath}"],
		"opts": {
			"recurse": true,
			"lenient": true,
			"template": "${templatePath}",
			"ui5": {
				"saveSymbols": true
			},
			"destination": "${destinationPath}"
		},
		"templates": {
			"ui5": {
				"variants": ${JSON.stringify(variants)},
				"version": "${version}",
				"jsapiFile": "${jsapiFilePath}",
				"apiJsonFolder": "${apiJsonFolderPath}",
				"apiJsonFile": "${apiJsonFilePath}"
			}
		}
	}`;
	return config;
}

/**
 * Write jsdoc-config.json to file system
 *
 * @private
 * @param {string} targetDirPath Directory Path to write the jsdoc-config.json file to
 * @param {string} config jsdoc-config.json content
 * @returns {string} Full path to the written jsdoc-config.json file
 */
async function writeJsdocConfig(targetDirPath, config) {
	const configPath = path.join(targetDirPath, "jsdoc-config.json");
	await writeFile(configPath, config);
	return configPath;
}


/**
 * Execute JSDoc build by spawning JSDoc as an external process
 *
 * @private
 * @param {Object} parameters Parameters
 * @param {string} parameters.sourcePath Project resources (input for JSDoc generation)
 * @param {string} parameters.configPath Full path to jsdoc-config.json file
 * @returns {Promise<undefined>}
 */
async function buildJsdoc({sourcePath, configPath}) {
	const args = [
		require.resolve("jsdoc/jsdoc"),
		"-c",
		configPath,
		"--verbose",
		sourcePath
	];
	return new Promise((resolve, reject) => {
		const child = spawn("node", args, {
			stdio: ["ignore", "ignore", process.stderr]
		});
		child.on("close", function(code) {
			if (code === 0 || code === 1) {
				resolve();
			} else {
				reject(new Error(`JSDoc child process closed with code ${code}`));
			}
		});
	});
}

module.exports = jsdocGenerator;
module.exports._generateJsdocConfig = generateJsdocConfig;
module.exports._writeJsdocConfig = writeJsdocConfig;
module.exports._buildJsdoc = buildJsdoc;