formatting
This commit is contained in:
parent
6ad9208119
commit
9cc7da09fc
72
src/docs.mts
72
src/docs.mts
|
@ -1,10 +1,11 @@
|
||||||
/* eslint-disable no-console */
|
/* eslint-disable no-console */
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* @file Transform documentation source files into files suitable for publishing and optionally copy
|
* @file Transform documentation source files into files suitable for publishing
|
||||||
* the transformed files from the source directory to the directory used for the final, published
|
* and optionally copy the transformed files from the source directory to the
|
||||||
* documentation directory. The list of files transformed and copied to final documentation
|
* directory used for the final, published documentation directory. The list
|
||||||
* directory are logged to the console. If a file in the source directory has the same contents in
|
* 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).
|
* the final directory, nothing is done (the final directory is up-to-date).
|
||||||
* @example
|
* @example
|
||||||
* docs
|
* docs
|
||||||
|
@ -23,12 +24,12 @@
|
||||||
* If the --git option is used, the command `git add docs` will be run after all transformations (and/or verifications) have completed successfully
|
* 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.
|
* 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
|
* @todo Ensure that the documentation source and final paths are correct by
|
||||||
* get their absolute paths. Ensures that the location of those 2 directories is not dependent on
|
* using process.cwd() to get their absolute paths. Ensures that the location
|
||||||
* where this file resides.
|
* 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
|
* @todo Write a test file for this. (Will need to be able to deal .mts file.
|
||||||
* it.)
|
* Jest has trouble with it.)
|
||||||
*/
|
*/
|
||||||
import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
|
import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
|
||||||
import { exec } from 'child_process';
|
import { exec } from 'child_process';
|
||||||
|
@ -67,13 +68,14 @@ const prettierConfig: prettier.Config = {
|
||||||
let filesWereTransformed = false;
|
let filesWereTransformed = false;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Given a source file name and path, return the documentation destination full path and file name
|
* Given a source file name and path, return the documentation destination full
|
||||||
* Create the destination path if it does not already exist.
|
* path and file name Create the destination path if it does not already exist.
|
||||||
*
|
*
|
||||||
* @param {string} file - Name of the file (including full path)
|
* @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
|
* @returns {string} Name of the file with the path changed from the source
|
||||||
* documentation directory
|
* directory to final documentation directory
|
||||||
* @todo Possible Improvement: combine with lint-staged to only copy files that have changed
|
* @todo Possible Improvement: combine with lint-staged to only copy files that
|
||||||
|
* have changed
|
||||||
*/
|
*/
|
||||||
const changeToFinalDocDir = (file: string): string => {
|
const changeToFinalDocDir = (file: string): string => {
|
||||||
const newDir = file.replace(SOURCE_DOCS_DIR, FINAL_DOCS_DIR);
|
const newDir = file.replace(SOURCE_DOCS_DIR, FINAL_DOCS_DIR);
|
||||||
|
@ -82,8 +84,8 @@ const changeToFinalDocDir = (file: string): string => {
|
||||||
};
|
};
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Log messages to the console showing if the transformed file copied to the final documentation
|
* Log messages to the console showing if the transformed file copied to the
|
||||||
* directory or still needs to be copied.
|
* final documentation directory or still needs to be copied.
|
||||||
*
|
*
|
||||||
* @param {string} filename Name of the file that was transformed
|
* @param {string} filename Name of the file that was transformed
|
||||||
* @param {boolean} wasCopied Whether or not the file was copied
|
* @param {boolean} wasCopied Whether or not the file was copied
|
||||||
|
@ -99,13 +101,14 @@ const logWasOrShouldBeTransformed = (filename: string, wasCopied: boolean) => {
|
||||||
};
|
};
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* If the file contents were transformed, set the _filesWereTransformed_ flag to true and copy the
|
* If the file contents were transformed, set the _filesWereTransformed_ flag to
|
||||||
* transformed contents to the final documentation directory if the doCopy flag is true. Log
|
* true and copy the transformed contents to the final documentation directory
|
||||||
* messages to the console.
|
* if the doCopy flag is true. Log messages to the console.
|
||||||
*
|
*
|
||||||
* @param {string} filename Name of the file that will be verified
|
* @param {string} filename Name of the file that will be verified
|
||||||
* @param {boolean} [doCopy=false] Whether we should copy that transformedContents to the final
|
* @param {boolean} [doCopy=false] Whether we should copy that
|
||||||
* documentation directory. Default is `false`
|
* transformedContents to the final documentation directory. Default is
|
||||||
|
* `false`. Default is `false`
|
||||||
* @param {string} [transformedContent] New contents for the file
|
* @param {string} [transformedContent] New contents for the file
|
||||||
*/
|
*/
|
||||||
const copyTransformedContents = (filename: string, doCopy = false, transformedContent?: string) => {
|
const copyTransformedContents = (filename: string, doCopy = false, transformedContent?: string) => {
|
||||||
|
@ -130,14 +133,15 @@ const readSyncedUTF8file = (filename: string): string => {
|
||||||
};
|
};
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Transform a markdown file and write the transformed file to the directory for published
|
* Transform a markdown file and write the transformed file to the directory for
|
||||||
* documentation
|
* published documentation
|
||||||
*
|
*
|
||||||
* 1. Add a `mermaid-example` block before every `mermaid` or `mmd` block On the docsify site (one
|
* 1. Add a `mermaid-example` block before every `mermaid` or `mmd` block On the
|
||||||
* place where the documentation is published), this will show the code used for the mermaid
|
* docsify site (one place where the documentation is published), this will
|
||||||
* diagram
|
* show the code used for the mermaid diagram
|
||||||
* 2. Add the text that says the file is automatically generated
|
* 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
|
* 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
|
* @param file {string} name of the file that will be verified
|
||||||
*/
|
*/
|
||||||
|
@ -164,17 +168,17 @@ const transformMarkdown = (file: string) => {
|
||||||
};
|
};
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Transform an HTML file and write the transformed file to the directory for published
|
* Transform an HTML file and write the transformed file to the directory for
|
||||||
* documentation
|
* published documentation
|
||||||
*
|
*
|
||||||
* - Add the text that says the file is automatically generated Verify that the file has been changed
|
* - Add the text that says the file is automatically generated Verify that the
|
||||||
* and write out the changes
|
* file has been changed and write out the changes
|
||||||
*
|
*
|
||||||
* @param filename {string} name of the HTML file to transform
|
* @param filename {string} name of the HTML file to transform
|
||||||
*/
|
*/
|
||||||
const transformHtml = (filename: string) => {
|
const transformHtml = (filename: string) => {
|
||||||
/**
|
/**
|
||||||
* Insert the '...auto generated...' comment into an HTML file after the <html> element
|
* Insert the '...auto generated...' comment into an HTML file after the<html> element
|
||||||
*
|
*
|
||||||
* @param fileName {string} file name that should have the comment inserted
|
* @param fileName {string} file name that should have the comment inserted
|
||||||
* @returns {string} The contents of the file with the comment inserted
|
* @returns {string} The contents of the file with the comment inserted
|
||||||
|
@ -204,7 +208,9 @@ const transformHtml = (filename: string) => {
|
||||||
const includeFilesStartingWithDot = true;
|
const includeFilesStartingWithDot = true;
|
||||||
|
|
||||||
console.log('Transforming markdown files...');
|
console.log('Transforming markdown files...');
|
||||||
const mdFiles = await globby([join(sourceDirGlob, '*.md')], { dot: includeFilesStartingWithDot });
|
const mdFiles = await globby([join(sourceDirGlob, '*.md')], {
|
||||||
|
dot: includeFilesStartingWithDot,
|
||||||
|
});
|
||||||
mdFiles.forEach(transformMarkdown);
|
mdFiles.forEach(transformMarkdown);
|
||||||
|
|
||||||
console.log('Transforming html files...');
|
console.log('Transforming html files...');
|
||||||
|
|
Loading…
Reference in New Issue