@gravityforms/gulp-tasks/src/scripts/generate-docs.js

Configurable Gulp tasks for use in Gravity Forms projects.

#!/usr/bin/env node

const fs = require( 'fs' );
const getConfig = require('../../config');
const { config } = getConfig();
const {
	asyncForEach,
	copyFolderSync,
	execShellCommand,
	extractCommentsToFiles,
	generateHTMLFiles,
	trailingSlashIt,
} = require( './util' );

const jsDocConfigNames = config?.generateDocs?.js?.docConfigNames || [];
const cssDocConfigs = config?.generateDocs?.css?.configs || [];

const generateJSDocs = async () => {
	if ( ! jsDocConfigNames.length ) {
		return;
	}
	// Copying files needed for index.html.
	await copyIndexFiles();

	const configPath = trailingSlashIt( config.paths.root );
	await asyncForEach( jsDocConfigNames, async ( docKey ) => {
		const docConfig = require( `${ configPath }/jsdoc.${ docKey }.conf.json` );
		if ( docConfig?.gf_opts?.static_dirs && docConfig?.gf_opts?.output_dir ) {
			await asyncForEach( docConfig.gf_opts.static_dirs, ( dir ) => {
				const dirNames = dir.split( '/' );
				copyFolderSync(
					`${ configPath }${ dir }`,
					`${ configPath }${ trailingSlashIt( docConfig.gf_opts.output_dir ) }${ dirNames[ dirNames.length - 1 ] }`
				);
			} );
		}
		await execShellCommand( `jsdoc -c '${ configPath }jsdoc.${ docKey }.conf.json'` );
	} );
};

const copyIndexFiles = async () => {
	const jsIndexPageDestDir = config?.generateDocs?.js?.indexPage.destDir || '';
	const jsIndexPageFiles = config?.generateDocs?.js?.indexPage.files || [];

	if ( ! jsIndexPageFiles.length ) {
		return;
	}

	// Making sure destination dir exists
	fs.mkdir( jsIndexPageDestDir, { recursive: true }, ( err ) => {
		if ( err ) {
			throw err;
		}

		jsIndexPageFiles.forEach( ( { src, dest } ) => copyFile( src, dest ) );
	} );
};

const copyFile = ( source, dest ) => {
	fs.copyFile( source, dest, ( err ) => {
		if ( err ) {
			console.log( 'Error copying ' + source, err );
		}
	} );
};

/**
 * @function init
 * @description Add all async processors for generating docs here.
 *
 * @since 1.3.25
 *
 * @returns {Promise<void>}
 */
const init = async () => {
	// @aaron actual runner for task you can run in root: `npm run generate:docs` then check in root docs directory for output
	await extractCommentsToFiles( cssDocConfigs );
	await generateJSDocs();
	await generateHTMLFiles( cssDocConfigs );
};

init().then( () => {
	console.log( 'Generated docs sites for all configs.' );
} );