builder/lib/tasks/jsdoc/generateJsdoc.js

  1. const log = require("@ui5/logger").getLogger("builder:tasks:jsdoc:generateJsdoc");
  2. const path = require("path");
  3. const makeDir = require("make-dir");
  4. const os = require("os");
  5. const fs = require("graceful-fs");
  6. const {promisify} = require("util");
  7. const mkdtemp = promisify(fs.mkdtemp);
  8. const rimraf = promisify(require("rimraf"));
  9. const jsdocGenerator = require("../../processors/jsdoc/jsdocGenerator");
  10. const {resourceFactory} = require("@ui5/fs");
  12. /**
  13.  *
  14.  * @public
  15.  * @typedef {object} GenerateJsdocOptions
  16.  * @property {string|string[]} pattern Pattern to locate the files to be processed
  17.  * @property {string} projectName Project name
  18.  * @property {string} namespace Namespace to build (e.g. <code>some/project/name</code>)
  19.  * @property {string} version Project version
  20.  */
  22. /**
  23.  * Task to execute a JSDoc build for UI5 projects
  24.  *
  25.  * @public
  26.  * @alias module:@ui5/builder.tasks.generateJsdoc
  27.  * @param {object} parameters Parameters
  28.  * @param {module:@ui5/fs.DuplexCollection} parameters.workspace DuplexCollection to read and write files
  29.  * @param {module:@ui5/fs.AbstractReader} parameters.dependencies Reader or Collection to read dependency files
  30.  * @param {GenerateJsdocOptions} parameters.options Options
  31.  * @param {module:@ui5/builder.tasks.TaskUtil|object} [parameters.taskUtil] TaskUtil
  32.  * @param {object} [parameters.buildContext] Internal, deprecated parameter
  33.  * @returns {Promise<undefined>} Promise resolving with <code>undefined</code> once data has been written
  34.  */
  35. const generateJsdoc = async function({
  36. 	taskUtil,
  37. 	buildContext,
  38. 	workspace,
  39. 	dependencies,
  40. 	options = {}
  41. }) {
  42. 	const {projectName, namespace, version, pattern} = /** @type {GenerateJsdocOptions} */ (options);
  44. 	if (!projectName || !namespace || !version || !pattern) {
  45. 		throw new Error("[generateJsdoc]: One or more mandatory options not provided");
  46. 	}
  48. 	const {sourcePath: resourcePath, targetPath, tmpPath, cleanup} =
  49. 		await generateJsdoc._createTmpDirs(projectName);
  51. 	// TODO 3.0: remove buildContext
  52. 	const _taskUtil = taskUtil || buildContext;
  53. 	if (_taskUtil) {
  54. 		_taskUtil.registerCleanupTask(cleanup);
  55. 	}
  57. 	const [writtenResourcesCount] = await Promise.all([
  58. 		generateJsdoc._writeResourcesToDir({
  59. 			workspace,
  60. 			pattern,
  61. 			targetPath: resourcePath
  62. 		}),
  63. 		generateJsdoc._writeDependencyApisToDir({
  64. 			dependencies,
  65. 			targetPath: path.join(tmpPath, "dependency-apis")
  66. 		})
  67. 	]);
  69. 	if (writtenResourcesCount === 0) {
  70. 		log.info(`Failed to find any input resources for project ${projectName} using pattern ` +
  71. 			`${pattern}. Skipping JSDoc generation...`);
  72. 		return;
  73. 	}
  75. 	const createdResources = await jsdocGenerator({
  76. 		sourcePath: resourcePath,
  77. 		targetPath,
  78. 		tmpPath,
  79. 		options: {
  80. 			projectName,
  81. 			namespace,
  82. 			version,
  83. 			variants: ["apijson"]
  84. 		}
  85. 	});
  87. 	await Promise.all(createdResources.map((resource) => {
  88. 		return workspace.write(resource);
  89. 	}));
  90. };
  92. /**
  93.  * Create temporary directories for JSDoc generation processor
  94.  *
  95.  * @private
  96.  * @param {string} projectName Project name used for naming the temporary working directory
  97.  * @returns {Promise<object>} Promise resolving with sourcePath, targetPath and tmpPath strings
  98.  */
  99. async function createTmpDirs(projectName) {
  100. 	const tmpDirPath = await generateJsdoc._createTmpDir(projectName);
  102. 	const sourcePath = path.join(tmpDirPath, "src"); // dir will be created by writing project resources below
  103. 	await makeDir(sourcePath, {fs});
  104. 	const targetPath = path.join(tmpDirPath, "target"); // dir will be created by jsdoc itself
  105. 	await makeDir(targetPath, {fs});
  107. 	const tmpPath = path.join(tmpDirPath, "tmp"); // dir needs to be created by us
  108. 	await makeDir(tmpPath, {fs});
  110. 	return {
  111. 		sourcePath,
  112. 		targetPath,
  113. 		tmpPath,
  114. 		cleanup: async () => {
  115. 			return rimraf(tmpDirPath);
  116. 		}
  117. 	};
  118. }
  120. /**
  121.  * Create a temporary directory on the host system
  122.  *
  123.  * @private
  124.  * @param {string} projectName Project name used for naming the temporary directory
  125.  * @returns {Promise<string>} Promise resolving with path of the temporary directory
  126.  */
  127. async function createTmpDir(projectName) {
  128. 	const sanitizedProjectName = projectName.replace(/[^A-Za-z0-9]/g, "");
  130. 	const tmpRootPath = path.join(os.tmpdir(), "ui5-tooling");
  131. 	await makeDir(tmpRootPath, {fs});
  133. 	// Appending minus sign also because node docs advise to "avoid trailing X characters in prefix"
  134. 	return mkdtemp(path.join(tmpRootPath, `jsdoc-${sanitizedProjectName}-`));
  135. }
  137. /**
  138.  * Write resources from workspace matching the given pattern to the given fs destination
  139.  *
  140.  * @private
  141.  * @param {object} parameters Parameters
  142.  * @param {module:@ui5/fs.DuplexCollection} parameters.workspace DuplexCollection to read and write files
  143.  * @param {string} parameters.pattern Pattern to match resources in workspace against
  144.  * @param {string} parameters.targetPath Path to write the resources to
  145.  * @returns {Promise<number>} Promise resolving with number of resources written to given directory
  146.  */
  147. async function writeResourcesToDir({workspace, pattern, targetPath}) {
  148. 	const fsTarget = resourceFactory.createAdapter({
  149. 		fsBasePath: targetPath,
  150. 		virBasePath: "/resources/"
  151. 	});
  153. 	let allResources;
  154. 	if (workspace.byGlobSource) { // API only available on duplex collections
  155. 		allResources = await workspace.byGlobSource(pattern);
  156. 	} else {
  157. 		allResources = await workspace.byGlob(pattern);
  158. 	}
  160. 	// write all resources to the tmp folder
  161. 	await Promise.all(allResources.map((resource) => fsTarget.write(resource)));
  162. 	return allResources.length;
  163. }
  165. /**
  166.  * Write api.json files of dependencies to given target path in a flat structure
  167.  *
  168.  * @private
  169.  * @param {object} parameters Parameters
  170.  * @param {module:@ui5/fs.AbstractReader} parameters.dependencies Reader or Collection to read dependency files
  171.  * @param {string} parameters.targetPath Path to write the resources to
  172.  * @returns {Promise<number>} Promise resolving with number of resources written to given directory
  173.  */
  174. async function writeDependencyApisToDir({dependencies, targetPath}) {
  175. 	const depApis = await dependencies.byGlob("/test-resources/**/designtime/api.json");
  177. 	// Clone resources before changing their path
  178. 	const apis = await Promise.all(depApis.map((resource) => resource.clone()));
  180. 	for (let i = 0; i < apis.length; i++) {
  181. 		apis[i].setPath(`/api-${i}.json`);
  182. 	}
  184. 	const fsTarget = resourceFactory.createAdapter({
  185. 		fsBasePath: targetPath,
  186. 		virBasePath: "/"
  187. 	});
  188. 	await Promise.all(apis.map((resource) => fsTarget.write(resource)));
  189. 	return apis.length;
  190. }
  192. module.exports = generateJsdoc;
  193. module.exports._createTmpDirs = createTmpDirs;
  194. module.exports._createTmpDir = createTmpDir;
  195. module.exports._writeResourcesToDir = writeResourcesToDir;
  196. module.exports._writeDependencyApisToDir = writeDependencyApisToDir;