From 6554a41f6dfd054d6540b4e101e25e4b7213780a Mon Sep 17 00:00:00 2001 From: "Ashley Engelund (weedySeaDragon @ github)" Date: Mon, 5 Sep 2022 18:39:36 -0700 Subject: [PATCH] transform HTML (insert comment); add console msgs and clarify; add file doc --- src/docs.mts | 71 +++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 65 insertions(+), 6 deletions(-) diff --git a/src/docs.mts b/src/docs.mts index 4ed1f7feb..d211e0fbf 100644 --- a/src/docs.mts +++ b/src/docs.mts @@ -1,6 +1,24 @@ +/** + * @overview Process and potentially transform documentation source files into files suitable for publishing. + * Copy files from the source directory (/src/docs) to the directory used for the final, published documentation (/docs). + * The list of files changed (transformed) and copied to /docs are logged to the console. + * If a file in /src/docs has the same contents in /docs, nothing is done (it is not copied to /docs). + * + * @example docs + * @example docs --verify + * If the --verify option is used, no files will be copied to /docs, but the list of files to be changed is still shown on the console. + * A message to the console will show that this command should be run without the --verify flag so that the 'docs' folder is be updated. + * Note that the command will return an exit code (1), which will show that it failed. + * @example docs --git + * If the --git option is used, the command `git add docs` will be run + * + */ + 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"; @@ -63,6 +81,10 @@ const verifyAndCopy = (file: string, content?: string) => { console.log(logMsg); }; +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 @@ -73,8 +95,8 @@ const verifyAndCopy = (file: string, content?: string) => { * * @param file {string} name of the file that will be verified */ -const transform = (file: string) => { - const doc = readFileSync(file, "utf8"); +const transformMarkdown = (file: string) => { + const doc = readSyncedUTF8file(file); const ast: Root = remark.parse(doc); const out = flatmap(ast, (c: Code) => { if (c.type !== "code" || !c.lang?.startsWith("mermaid")) { @@ -102,17 +124,54 @@ const transform = (file: string) => { ); }; +/** + * Transform a 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 + * + * @param filename {string} name of the HTML file to transform + */ +const transformHtml = (filename: string) => { + + /** + * Insert the '...auto generated...' comment into an HTML file after the element + * + * @param fname {string} file name that should have the comment inserted + * @returns {string} the contents of the file with the comment inserted + */ + function insertAutoGeneratedComment(fname: string): string { + const fileContents = readSyncedUTF8file(fname); + const jsdom = new JSDOM(fileContents); + const htmlDoc = jsdom.window.document; + const autoGeneratedComment = jsdom.window.document.createComment(AUTOGENERATED_TEXT); + + let rootElement = htmlDoc.documentElement; + rootElement.prepend(autoGeneratedComment); + return jsdom.serialize(); + } + + let transformedHTML = insertAutoGeneratedComment(filename); + verifyAndCopy(filename, transformedHTML); +}; + (async () => { + console.log("Transforming markdown files..."); const mdFiles = await globby(["./src/docs/**/*.md"], { dot: true }); - mdFiles.forEach(transform); - const nonMDFiles = await globby(["src/docs/**", "!**/*.md"], { dot: true }); - nonMDFiles.forEach((file) => { + mdFiles.forEach(transformMarkdown); + + console.log("Transforming html files..."); + const htmlFiles = await globby(["./src/docs/**/*.html"], { dot: true }); + htmlFiles.forEach(transformHtml); + + console.log("Transforming all other files..."); + const otherFiles = await globby(["src/docs/**", "!**/*.md", "!**/*.html"], { dot: true }); + otherFiles.forEach((file) => { verifyAndCopy(file); }); if (filesWereChanged) { if (verifyOnly) { console.log( - "Changes detected in files in `docs`. Please run `yarn docs:build` after making changes to 'src/docs' to update the `docs` folder." + "Changes detected in files in `src/docs`. Please run `yarn docs:build` after making changes to 'src/docs' to update the `docs` folder." ); process.exit(1); }