diff --git a/src/docs.mts b/src/docs.mts index 877f7a022..738e4c9c9 100644 --- a/src/docs.mts +++ b/src/docs.mts @@ -20,13 +20,18 @@ * docs --git * If the --git option is used, the command `git add docs` will be run after all transformations (and/or verifications) have completed successfully * If not files were transformed, the git command is not run. + * + * @todo Ensure that the documentation source and final paths are correct by using process.cwd() to + * get their absolute paths. Ensures that the location of those 2 directories is not dependent on + * where this file resides. + * + * @todo Write a test file for this. (Will need to be able to deal with globby. Jest has trouble with it. */ import { remark } from 'remark'; import type { Code, Root } from 'mdast'; import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs'; import { JSDOM } from 'jsdom'; - // @ts-ignore import flatmap from 'unist-util-flatmap'; import { globby } from 'globby'; @@ -35,36 +40,35 @@ import { exec } from 'child_process'; // @ts-ignore import prettier from 'prettier'; -const SOURCE_DOCS_DIR = 'src/docs/'; -const FINAL_DOCS_DIR = 'docs/'; -const AUTOGENERATED_TEXT = - '# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in ${SOURCE_DOCS_DIR}.'; +const SOURCE_DOCS_DIR = 'src/docs'; +const FINAL_DOCS_DIR = 'docs'; + +const AUTOGENERATED_TEXT = `# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in ${SOURCE_DOCS_DIR}.`; const LOGMSG_TRANSFORMED = 'transformed'; const LOGMSG_TO_BE_TRANSFORMED = 'to be transformed'; -const LOGMSG_COPIED = ' ...and copied to ${FINAL_DOCS_DIR}'; +const LOGMSG_COPIED = ` ...and copied to ${FINAL_DOCS_DIR}`; -const WARN_DOCSDIR_DOESNT_MATCH = - "Changed files were transformed in `${SOURCE_DOCS_DIR}` but do not match the files in `${FINAL_DOCS_DIR}`. Please run `yarn docs:build` after making changes to '${SOURCE_DOCS_DIR}' to update the `${FINAL_DOCS_DIR}` directory with the transformed files."; +const WARN_DOCSDIR_DOESNT_MATCH = `Changed files were transformed in ${SOURCE_DOCS_DIR} but do not match the files in ${FINAL_DOCS_DIR}. Please run yarn docs:build after making changes to ${SOURCE_DOCS_DIR} to update the ${FINAL_DOCS_DIR} directory with the transformed files.`; -const verifyOnly = process.argv.includes('--verify'); -const git = process.argv.includes('--git'); +const verifyOnly: boolean = process.argv.includes('--verify'); +const git: boolean = process.argv.includes('--git'); let filesWereTransformed = false; /** * Given a source file name and path, return the documentation destination full path and file name - * Create the destination path if it does not already exist. Possible Improvement: combine with - * lint-staged to only copy files that have changed + * Create the destination path if it does not already exist. * * @param {string} file - Name of the file (including full path) * @returns {string} Name of the file with the path changed from the source directory to final * documentation directory + * @todo Possible Improvement: combine with lint-staged to only copy files that have changed */ -const prepareOutFile = (file: string): string => { - const outFile = join(FINAL_DOCS_DIR, file.replace(SOURCE_DOCS_DIR, '')); - mkdirSync(dirname(outFile), { recursive: true }); - return outFile; +const changeToFinalDocDir = (file: string): string => { + const newDir = file.replace(SOURCE_DOCS_DIR, FINAL_DOCS_DIR); + mkdirSync(dirname(newDir), { recursive: true }); + return newDir; }; /** @@ -100,8 +104,10 @@ const copyTransformedContents = ( transformedContent?: string, doCopy: boolean = false ) => { - const outFile = prepareOutFile(file); - const existingBuffer = existsSync(outFile) ? readFileSync(outFile) : Buffer.from('#NEW FILE#'); + const fileInFinalDocDir = changeToFinalDocDir(file); + const existingBuffer = existsSync(fileInFinalDocDir) + ? readFileSync(fileInFinalDocDir) + : Buffer.from('#NEW FILE#'); const newBuffer = transformedContent ? Buffer.from(transformedContent) : readFileSync(file); if (existingBuffer.equals(newBuffer)) { return; // Files are same, skip. @@ -109,7 +115,7 @@ const copyTransformedContents = ( filesWereTransformed = true; if (doCopy) { - writeFileSync(outFile, newBuffer); + writeFileSync(fileInFinalDocDir, newBuffer); } logWasOrShouldBeTransformed(fileInFinalDocDir, doCopy); }; @@ -185,7 +191,7 @@ const transformHtml = (filename: string) => { }; const transformedHTML = insertAutoGeneratedComment(filename); - copyTransformedContents(filename, transformedHTML); + copyTransformedContents(filename, transformedHTML, !verifyOnly); }; /** Main method (entry point) */