diff --git a/src/docs.mts b/src/docs.mts index 7f1fe9d50..e04296424 100644 --- a/src/docs.mts +++ b/src/docs.mts @@ -68,40 +68,59 @@ const prepareOutFile = (file: string): string => { }; /** - * Verify that a file was changed and (potentially) write the new contents out to the file. Log a message to the console - * If the file was not changed, do nothing. (No message is logged to the console.) + * Log messages to the console showing if the transformed file copied to the final documentation + * directory or still needs to be copied. * - * @param file {string} name of the file that will be verified - * @param content {string} new contents for the file + * @param {string} filename Name of the file that was transformed + * @param {boolean} wasCopied Whether or not the file was copied */ -const verifyAndCopy = (file: string, content?: string) => { - const outFile = prepareOutFile(file); - const existingBuffer = existsSync(outFile) ? readFileSync(outFile) : Buffer.from('#NEW FILE#'); - const newBuffer = content ? Buffer.from(content) : readFileSync(file); - if (existingBuffer.equals(newBuffer)) { - // Files are same, skip. - return; - } - let changeMsg = 'changed'; - if (verifyOnly) { - changeMsg = 'to be changed'; - } - let logMsg = ` File ${changeMsg}: ${outFile}`; - - filesWereChanged = true; - if (!verifyOnly) { - writeFileSync(outFile, newBuffer); - logMsg += ' ...and copied to /docs'; +const logWasOrShouldBeTransformed = (filename: string, wasCopied: boolean) => { + let changeMsg: string; + let logMsg: string; + changeMsg = wasCopied ? LOGMSG_TRANSFORMED : LOGMSG_TO_BE_TRANSFORMED; + logMsg = ` File ${changeMsg}: ${filename}`; + if (wasCopied) { + logMsg += LOGMSG_COPIED; } console.log(logMsg); }; +/** + * If the file contents were transformed, set the _filesWereTransformed_ flag to true and copy the + * transformed contents to the final documentation directory if the doCopy flag is true. Log + * messages to the console. + * + * @param {string} file Name of the file that will be verified + * @param {string} [transformedContent] New contents for the file + * @param {boolean} [doCopy=false] Whether we should copy that transformedContents to the final + * documentation directory. Default is `false` + */ +const copyTransformedContents = ( + file: string, + transformedContent?: string, + doCopy: boolean = false +) => { + const outFile = prepareOutFile(file); + const existingBuffer = existsSync(outFile) ? readFileSync(outFile) : Buffer.from('#NEW FILE#'); + const newBuffer = transformedContent ? Buffer.from(transformedContent) : readFileSync(file); + if (existingBuffer.equals(newBuffer)) { + return; // Files are same, skip. + } + + filesWereTransformed = true; + if (doCopy) { + writeFileSync(outFile, newBuffer); + } + logWasOrShouldBeTransformed(outFile, doCopy); +}; + const readSyncedUTF8file = (file: string): string => { return readFileSync(file, 'utf8'); }; /** * Transform a markdown file and write the transformed file to the directory for published documentation + * * 1. Add a `mermaid-example` block before every `mermaid` or `mmd` block On the docsify site (one * place where the documentation is published), this will show the code used for the mermaid diagram * 2. Add the text that says the file is automatically generated @@ -125,7 +144,7 @@ const transformMarkdown = (file: string) => { // Add the AUTOGENERATED_TEXT to the start of the file const transformed = `${AUTOGENERATED_TEXT}\n${remark.stringify(out)}`; - verifyAndCopy( + copyTransformedContents( file, prettier.format(transformed, { parser: 'markdown', @@ -140,6 +159,7 @@ const transformMarkdown = (file: string) => { /** * Transform an HTML file and write the transformed file to the directory for published documentation + * * - Add the text that says the file is automatically generated Verify that the file has been changed * and write out the changes * @@ -161,10 +181,10 @@ const transformHtml = (filename: string) => { const rootElement = htmlDoc.documentElement; rootElement.prepend(autoGeneratedComment); return jsdom.serialize(); - } + }; const transformedHTML = insertAutoGeneratedComment(filename); - verifyAndCopy(filename, transformedHTML); + copyTransformedContents(filename, transformedHTML); }; /** Main method (entry point) */ @@ -187,9 +207,10 @@ const transformHtml = (filename: string) => { dot: includeFilesStartingWithDot, }); otherFiles.forEach((file) => { - verifyAndCopy(file); + copyTransformedContents(file); }); - if (filesWereChanged) { + + if (filesWereTransformed) { if (verifyOnly) { console.log(WARN_DOCSDIR_DOESNT_MATCH); process.exit(1);