diff --git a/.lintstagedrc.json b/.lintstagedrc.json index db16ea99a..b88abda4b 100644 --- a/.lintstagedrc.json +++ b/.lintstagedrc.json @@ -1,4 +1,5 @@ { "src/docs/**": ["yarn docs:build --git"], - "*.{ts,js,json,html,md}": ["eslint --fix", "prettier --write"] + "src/docs.mts": ["yarn docs:build --git"], + "*.{ts,js,json,html,md,mts}": ["eslint --fix", "prettier --write"] } diff --git a/docs/8.6.0_docs.md b/docs/8.6.0_docs.md index b532a1c94..9cced28ca 100644 --- a/docs/8.6.0_docs.md +++ b/docs/8.6.0_docs.md @@ -1,4 +1,4 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs. +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs. # Version 8.6.0 Changes diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index d676920b7..20f7afe3a 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -1,4 +1,4 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs. +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs. # Change Log diff --git a/docs/Configuration.md b/docs/Configuration.md index 0df2de104..1cbaa228f 100644 --- a/docs/Configuration.md +++ b/docs/Configuration.md @@ -1,4 +1,4 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs. +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs. # Configuration diff --git a/docs/README.md b/docs/README.md index 9e149dfdb..e22276488 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,4 +1,4 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs. +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs. # About Mermaid diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 0d32a7010..1b6153b89 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -1,4 +1,4 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs. +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs. # Summary diff --git a/docs/Setup.md b/docs/Setup.md index 2ef56e1d8..8e428c14c 100644 --- a/docs/Setup.md +++ b/docs/Setup.md @@ -1,4 +1,4 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs. +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs. diff --git a/docs/Tutorials.md b/docs/Tutorials.md index 0211d35d0..0eac9ccfe 100644 --- a/docs/Tutorials.md +++ b/docs/Tutorials.md @@ -1,4 +1,4 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs. +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs. # Tutorials diff --git a/docs/_navbar.md b/docs/_navbar.md index 6ec266461..222926fc4 100644 --- a/docs/_navbar.md +++ b/docs/_navbar.md @@ -1,4 +1,4 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs. +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs. - Getting started diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 40e46d835..a97bd8d72 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -1,4 +1,4 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs. +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs. - 📔 Introduction diff --git a/docs/accessibility.md b/docs/accessibility.md index 820fe364a..70ebef9d1 100644 --- a/docs/accessibility.md +++ b/docs/accessibility.md @@ -1,4 +1,4 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs. +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs. # Accessibility Options diff --git a/docs/breakingChanges.md b/docs/breakingChanges.md index f5bb4ddb3..01088b9dc 100644 --- a/docs/breakingChanges.md +++ b/docs/breakingChanges.md @@ -1,4 +1,4 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs. +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs. # Breaking changes diff --git a/docs/c4c.md b/docs/c4c.md index 1b4251785..48688f1a0 100644 --- a/docs/c4c.md +++ b/docs/c4c.md @@ -1,4 +1,4 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs. +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs. # C4 Diagrams diff --git a/docs/classDiagram.md b/docs/classDiagram.md index 1576aaa17..6c9ae96fe 100644 --- a/docs/classDiagram.md +++ b/docs/classDiagram.md @@ -1,4 +1,4 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs. +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs. # Class diagrams diff --git a/docs/developer-docs/configuration.md b/docs/developer-docs/configuration.md index a10954416..e764e200a 100644 --- a/docs/developer-docs/configuration.md +++ b/docs/developer-docs/configuration.md @@ -1,4 +1,4 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs. +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs. # Configuration diff --git a/docs/development.md b/docs/development.md index 365f639d7..70762be86 100644 --- a/docs/development.md +++ b/docs/development.md @@ -1,4 +1,4 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs. +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs. # Development and Contribution 🙌 diff --git a/docs/diagrams-and-syntax-and-examples/flowchart.md b/docs/diagrams-and-syntax-and-examples/flowchart.md index 3aef42ef7..0f798d27f 100644 --- a/docs/diagrams-and-syntax-and-examples/flowchart.md +++ b/docs/diagrams-and-syntax-and-examples/flowchart.md @@ -1,4 +1,4 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs. +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs. --- diff --git a/docs/directives.md b/docs/directives.md index 943dac53f..8ef732008 100644 --- a/docs/directives.md +++ b/docs/directives.md @@ -1,4 +1,4 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs. +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs. # Directives diff --git a/docs/entityRelationshipDiagram.md b/docs/entityRelationshipDiagram.md index 34e6a3ac6..1f24796b6 100644 --- a/docs/entityRelationshipDiagram.md +++ b/docs/entityRelationshipDiagram.md @@ -1,4 +1,4 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs. +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs. # Entity Relationship Diagrams diff --git a/docs/examples.md b/docs/examples.md index 174a2c986..d717083c6 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -1,4 +1,4 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs. +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs. # Examples diff --git a/docs/faq.md b/docs/faq.md index a1b6e4837..ac5eeeb80 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -1,4 +1,4 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs. +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs. # Frequently Asked Questions diff --git a/docs/flowchart.md b/docs/flowchart.md index 4d469f55e..3ff17ad02 100644 --- a/docs/flowchart.md +++ b/docs/flowchart.md @@ -1,4 +1,4 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs. +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs. # Flowcharts - Basic Syntax diff --git a/docs/gantt.md b/docs/gantt.md index b0a302d9f..9d598d977 100644 --- a/docs/gantt.md +++ b/docs/gantt.md @@ -1,4 +1,4 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs. +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs. # Gantt diagrams diff --git a/docs/gitgraph.md b/docs/gitgraph.md index c423c2515..5f86cf53c 100644 --- a/docs/gitgraph.md +++ b/docs/gitgraph.md @@ -1,4 +1,4 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs. +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs. # Gitgraph Diagrams diff --git a/docs/index.html b/docs/index.html index 39d454533..8d291f8e5 100644 --- a/docs/index.html +++ b/docs/index.html @@ -1,6 +1,6 @@ - + mermaid - Markdownish syntax for generating flowcharts, sequence diagrams, class diagrams, diff --git a/docs/integrations.md b/docs/integrations.md index 16e735779..57d3bd316 100644 --- a/docs/integrations.md +++ b/docs/integrations.md @@ -1,4 +1,4 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs. +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs. # Integrations diff --git a/docs/introduction.md b/docs/introduction.md index 38c7c7a0e..992fbafc1 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -1 +1 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs. +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs. diff --git a/docs/landing/index.html b/docs/landing/index.html index 9b1e3749f..2431ad9bd 100644 --- a/docs/landing/index.html +++ b/docs/landing/index.html @@ -1,6 +1,6 @@ <!DOCTYPE html> <html lang="en"> - <head> + <!--# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.--><head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <meta http-equiv="X-UA-Compatible" content="ie=edge" /> @@ -64,7 +64,7 @@ using Mermaid.js. </p> <a - href="https://www.amazon.com/Official-Guide-Mermaid-js-beautiful-flowcharts-dp-1801078025/dp/1801078025/ref=mt_other?_encoding=UTF8&me=&qid=1628153965" + href="https://www.amazon.com/Official-Guide-Mermaid-js-beautiful-flowcharts-dp-1801078025/dp/1801078025/ref=mt_other?_encoding=UTF8&me=&qid=1628153965" > <button style="background: #ffa41c; border: 1px solid #ff8f00" @@ -322,7 +322,7 @@ </p> </h3> <a - href="https://www.amazon.com/Official-Guide-Mermaid-js-beautiful-flowcharts-dp-1801078025/dp/1801078025/ref=mt_other?_encoding=UTF8&me=&qid=1628153965" + href="https://www.amazon.com/Official-Guide-Mermaid-js-beautiful-flowcharts-dp-1801078025/dp/1801078025/ref=mt_other?_encoding=UTF8&me=&qid=1628153965" > <button style="background: #ffa41c; border: 1px solid #ff8f00" diff --git a/docs/mermaidCLI.md b/docs/mermaidCLI.md index e3249315b..0d32c5472 100644 --- a/docs/mermaidCLI.md +++ b/docs/mermaidCLI.md @@ -1,4 +1,4 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs. +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs. # mermaid CLI diff --git a/docs/mindmap.md b/docs/mindmap.md index 8a7e21eb7..3d435d68a 100644 --- a/docs/mindmap.md +++ b/docs/mindmap.md @@ -1,4 +1,4 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs. +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs. # Mindmap diff --git a/docs/n00b-advanced.md b/docs/n00b-advanced.md index 4e9d74b98..b8970142a 100644 --- a/docs/n00b-advanced.md +++ b/docs/n00b-advanced.md @@ -1,4 +1,4 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs. +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs. # Advanced n00b mermaid (Coming soon..) diff --git a/docs/n00b-gettingStarted.md b/docs/n00b-gettingStarted.md index f3ade5559..505542539 100644 --- a/docs/n00b-gettingStarted.md +++ b/docs/n00b-gettingStarted.md @@ -1,4 +1,4 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs. +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs. # A Mermaid User-Guide for Beginners diff --git a/docs/n00b-overview.md b/docs/n00b-overview.md index 913fcc2f6..c109b63f2 100644 --- a/docs/n00b-overview.md +++ b/docs/n00b-overview.md @@ -1,4 +1,4 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs. +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs. # Overview for Beginners diff --git a/docs/n00b-syntaxReference.md b/docs/n00b-syntaxReference.md index 9f18e3d28..d25c6425e 100644 --- a/docs/n00b-syntaxReference.md +++ b/docs/n00b-syntaxReference.md @@ -1,4 +1,4 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs. +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs. # Diagram Syntax diff --git a/docs/newDiagram.md b/docs/newDiagram.md index e2191f1de..285cb7637 100644 --- a/docs/newDiagram.md +++ b/docs/newDiagram.md @@ -1,4 +1,4 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs. +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs. # Adding a New Diagram/Chart 📊 diff --git a/docs/pie.md b/docs/pie.md index 1e13e3872..79dcbfee5 100644 --- a/docs/pie.md +++ b/docs/pie.md @@ -1,4 +1,4 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs. +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs. # Pie chart diagrams diff --git a/docs/requirementDiagram.md b/docs/requirementDiagram.md index c510183d9..d31967871 100644 --- a/docs/requirementDiagram.md +++ b/docs/requirementDiagram.md @@ -1,4 +1,4 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs. +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs. # Requirement Diagram diff --git a/docs/security.md b/docs/security.md index e2990eb5b..ee9033ca2 100644 --- a/docs/security.md +++ b/docs/security.md @@ -1,4 +1,4 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs. +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs. # Security diff --git a/docs/sequenceDiagram.md b/docs/sequenceDiagram.md index ae0bd5e45..97968a676 100644 --- a/docs/sequenceDiagram.md +++ b/docs/sequenceDiagram.md @@ -1,4 +1,4 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs. +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs. # Sequence diagrams diff --git a/docs/stateDiagram.md b/docs/stateDiagram.md index 6af3b0bc4..8ea9fd239 100644 --- a/docs/stateDiagram.md +++ b/docs/stateDiagram.md @@ -1,4 +1,4 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs. +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs. # State diagrams diff --git a/docs/theming.md b/docs/theming.md index 287499eff..9ba136ec4 100644 --- a/docs/theming.md +++ b/docs/theming.md @@ -1,4 +1,4 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs. +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs. # Theme Configuration diff --git a/docs/upgrading.md b/docs/upgrading.md index fd7f72d82..c4d7bd3bd 100644 --- a/docs/upgrading.md +++ b/docs/upgrading.md @@ -1,4 +1,4 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs. +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs. # Upgrading diff --git a/docs/usage.md b/docs/usage.md index 02bd1bb13..e59670d02 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -1,4 +1,4 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs. +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs. # Usage diff --git a/docs/user-journey.md b/docs/user-journey.md index 9e213f425..e0d924f85 100644 --- a/docs/user-journey.md +++ b/docs/user-journey.md @@ -1,4 +1,4 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs. +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs. # User Journey Diagram diff --git a/src/docs.mts b/src/docs.mts index 5bc3a49cf..06a1f4bff 100644 --- a/src/docs.mts +++ b/src/docs.mts @@ -1,42 +1,152 @@ /* eslint-disable no-console */ -import { remark } from 'remark'; -import type { Code, Root } from 'mdast'; +/** + * @file Transform documentation source files into files suitable for publishing + * and optionally copy the transformed files from the source directory to the + * directory used for the final, published documentation directory. The list + * of files transformed and copied to final documentation directory are logged + * to the console. If a file in the source directory has the same contents in + * the final directory, nothing is done (the final directory is up-to-date). + * @example + * docs + * Run with no option flags + * + * @example + * docs --verify + * If the --verify option is used, it only _verifies_ that the final directory has been updated with the transformed files in the source directory. + * No files will be copied to the final documentation directory, but the list of files to be changed is shown on the console. + * If the final documentation directory does not have the transformed files from source directory + * - a message to the console will show that this command should be run without the --verify flag so that the final directory is updated, and + * - it will return a fail exit code (1) + * + * @example + * 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 .mts file. + * Jest has trouble with it.) + */ import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs'; -// @ts-ignore: no typings -import flatmap from 'unist-util-flatmap'; -import { globby } from 'globby'; -import { join, dirname } from 'path'; import { exec } from 'child_process'; +import { globby } from 'globby'; +import { JSDOM } from 'jsdom'; +import type { Code, Root } from 'mdast'; +import { join, dirname } from 'path'; import prettier from 'prettier'; +import { remark } from 'remark'; +// @ts-ignore No typescript declaration file +import flatmap from 'unist-util-flatmap'; -const verify = process.argv.includes('--verify'); -const git = process.argv.includes('--git'); -let fileChanged = false; -// Possible Improvement: combine with lint-staged to only copy files that have changed -const prepareOutFile = (file: string): string => { - const outFile = join('docs', file.replace('src/docs/', '')); - mkdirSync(dirname(outFile), { recursive: true }); - return outFile; +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 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: boolean = process.argv.includes('--verify'); +const git: boolean = process.argv.includes('--git'); + +// TODO: Read from .prettierrc? +const prettierConfig: prettier.Config = { + useTabs: false, + tabWidth: 2, + endOfLine: 'auto', + printWidth: 100, + singleQuote: true, }; -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); +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. + * + * @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 changeToFinalDocDir = (file: string): string => { + const newDir = file.replace(SOURCE_DOCS_DIR, FINAL_DOCS_DIR); + mkdirSync(dirname(newDir), { recursive: true }); + return newDir; +}; + +/** + * Log messages to the console showing if the transformed file copied to the + * final documentation directory or still needs to be copied. + * + * @param {string} filename Name of the file that was transformed + * @param {boolean} wasCopied Whether or not the file was copied + */ +const logWasOrShouldBeTransformed = (filename: string, wasCopied: boolean) => { + const changeMsg = wasCopied ? LOGMSG_TRANSFORMED : LOGMSG_TO_BE_TRANSFORMED; + let logMsg: string; + 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} filename Name of the file that will be verified + * @param {boolean} [doCopy=false] Whether we should copy that + * transformedContents to the final documentation directory. Default is + * `false`. Default is `false` + * @param {string} [transformedContent] New contents for the file + */ +const copyTransformedContents = (filename: string, doCopy = false, transformedContent?: string) => { + const fileInFinalDocDir = changeToFinalDocDir(filename); + const existingBuffer = existsSync(fileInFinalDocDir) + ? readFileSync(fileInFinalDocDir) + : Buffer.from('#NEW FILE#'); + const newBuffer = transformedContent ? Buffer.from(transformedContent) : readFileSync(filename); if (existingBuffer.equals(newBuffer)) { - // Files are same, skip. - return; + return; // Files are same, skip. } - console.log(`File changed: ${outFile}`); - fileChanged = true; - if (!verify) { - writeFileSync(outFile, newBuffer); + + filesWereTransformed = true; + if (doCopy) { + writeFileSync(fileInFinalDocDir, newBuffer); } + logWasOrShouldBeTransformed(fileInFinalDocDir, doCopy); }; -const transform = (file: string) => { - const doc = readFileSync(file, 'utf8'); +const readSyncedUTF8file = (filename: string): string => { + return readFileSync(filename, '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 + * 3. Use prettier to format the file Verify that the file has been changed and + * write out the changes + * + * @param file {string} name of the file that will be verified + */ +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')) { @@ -48,38 +158,82 @@ const transform = (file: string) => { return [c, Object.assign({}, c, { lang: 'mermaid' })]; }); - const transformed = `# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.\n${remark.stringify( - out - )}`; - verifyAndCopy( - file, - prettier.format(transformed, { - parser: 'markdown', - useTabs: false, - tabWidth: 2, - endOfLine: 'auto', - printWidth: 100, - singleQuote: true, - }) - ); + // Add the AUTOGENERATED_TEXT to the start of the file + const transformed = `${AUTOGENERATED_TEXT}\n${remark.stringify(out)}`; + const formatted = prettier.format(transformed, { + parser: 'markdown', + ...prettierConfig, + }); + copyTransformedContents(file, !verifyOnly, formatted); }; -(async () => { - const mdFiles = await globby(['./src/docs/**/*.md'], { dot: true }); - mdFiles.forEach(transform); - const nonMDFiles = await globby(['src/docs/**', '!**/*.md'], { dot: true }); - nonMDFiles.forEach((file) => { - verifyAndCopy(file); +/** + * 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 + * + * @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<html> element + * + * @param fileName {string} file name that should have the comment inserted + * @returns {string} The contents of the file with the comment inserted + */ + const insertAutoGeneratedComment = (fileName: string): string => { + const fileContents = readSyncedUTF8file(fileName); + const jsdom = new JSDOM(fileContents); + const htmlDoc = jsdom.window.document; + const autoGeneratedComment = jsdom.window.document.createComment(AUTOGENERATED_TEXT); + + const rootElement = htmlDoc.documentElement; + rootElement.prepend(autoGeneratedComment); + return jsdom.serialize(); + }; + + const transformedHTML = insertAutoGeneratedComment(filename); + const formattedHTML = prettier.format(transformedHTML, { + parser: 'html', + ...prettierConfig, }); - if (fileChanged) { - if (verify) { - console.log( - "Changes detected in files in `docs`. Please run `yarn docs:build` after making changes to 'src/docs' to update the `docs` folder." - ); + copyTransformedContents(filename, !verifyOnly, formattedHTML); +}; + +/** Main method (entry point) */ +(async () => { + const sourceDirGlob = join('.', SOURCE_DOCS_DIR, '**'); + const includeFilesStartingWithDot = true; + + console.log('Transforming markdown files...'); + const mdFiles = await globby([join(sourceDirGlob, '*.md')], { + dot: includeFilesStartingWithDot, + }); + mdFiles.forEach(transformMarkdown); + + console.log('Transforming html files...'); + const htmlFiles = await globby([join(sourceDirGlob, '*.html')], { + dot: includeFilesStartingWithDot, + }); + htmlFiles.forEach(transformHtml); + + console.log('Transforming all other files...'); + const otherFiles = await globby([sourceDirGlob, '!**/*.md', '!**/*.html'], { + dot: includeFilesStartingWithDot, + }); + otherFiles.forEach((file: string) => { + copyTransformedContents(file, !verifyOnly); // no transformation + }); + + if (filesWereTransformed) { + if (verifyOnly) { + console.log(WARN_DOCSDIR_DOESNT_MATCH); process.exit(1); } if (git) { - console.log('Adding changes in docs folder to git'); + console.log('Adding changes in ${FINAL_DOCS_DIR} folder to git'); exec('git add docs'); } }