simplfy method to copy transformation to /docs; extract logging
Extract the logging so that it if later we want to turn it on/off with a --verbose flag
This commit is contained in:
parent
a878edfb9b
commit
411d641aa2
75
src/docs.mts
75
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);
|
||||
|
|
Loading…
Reference in New Issue