Added scripts

Author: siefkenj

.gitignore

@@ -1,3 +1,7 @@
 dist
 node_modules
 tsconfig.tsbuildinfo
+debugging
+.vscode
+vscode*
+table-generation/generated

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 Jason Siefken
+Copyright (c) 2015-2022 Michael Brade, Jason Siefken
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package-lock.json

@@ -17,13 +17,20 @@
         "esbuild": "^0.14.39",
         "esbuild-jest": "^0.5.0",
         "esbuild-node-externals": "^1.4.1",
+        "esbuild-runner": "^2.2.1",
         "jest": "^28.1.0",
+        "mdast-builder": "^1.1.1",
+        "mdast-util-inject": "^1.1.0",
         "mkdirp": "^1.0.4",
         "pegjs": "^0.10.0",
         "pegjs-loader": "^0.5.6",
         "prettier": "^2.6.2",
         "prettier-plugin-pegjs": "^0.5.0",
+        "remark-gfm": "^3.0.1",
+        "remark-parse": "^10.0.1",
+        "remark-stringify": "^10.0.2",
         "ts-jest": "^28.0.2",
+        "ts-morph": "^14.0.0",
         "typescript": "^4.6.4"
     },
     "dependencies": {

package.json

@@ -0,0 +1,136 @@
+/**
+ * Autogenerate documentation for source files. This assumes a very specific format.
+ *
+ * run with
+ * ```
+ * npx esr scripts/build-docs.ts
+ * ```
+ */
+
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { Project, Node } from "ts-morph";
+
+const README_COMMENT: string = `<!-- DO NOT MODIFY -->
+<!-- This file was autogenerated by build-docs.ts -->
+<!-- Edit the docstring in index.ts and regenerate -->
+<!-- rather than editing this file directly. -->
+`;
+
+// We can only import ESM modules via async import, so all the action happens here.
+(async function () {
+    const chalk = await (await import("chalk")).default;
+    const { unified } = await import("unified");
+    const inject = await (await import("mdast-util-inject")).default;
+    const b = await import("mdast-builder");
+    const { getDataOnAllExports } = await import("./libs/get-symbols");
+    const {
+        gfmRemark,
+        makeConstantsSection,
+        makeFunctionsSection,
+        makeTypesSection,
+        makePluginsSection,
+    } = await (
+        await import("./libs/markdown-utils")
+    ).default;
+    type MdNode = ReturnType<typeof b.text>;
+
+    ///////////////////////////////////////////////////////////
+    // Build the documentation for all exports
+    ///////////////////////////////////////////////////////////
+    const project = new Project();
+    project.addSourceFilesAtPaths("./packages/**/*.ts");
+
+    // Find all the files we want to process. These have th form .../unified-latex.../index.ts,
+    // however we only want the top-level index.ts files (no any that may be in subdirectories).
+
+    const filesToProcess = project
+        .getSourceFiles()
+        .filter((file) =>
+            file.getFilePath().match(/unified-latex[^/]*\/index\.ts/)
+        );
+
+    console.log(chalk.bold("Processing"), filesToProcess.length, "files");
+    for (const file of filesToProcess) {
+        console.log(
+            "   ",
+            chalk.magenta(file.getDirectory().getBaseName()),
+            `/ ${file.getBaseName()}`
+        );
+
+        const outPath = path.join(file.getDirectoryPath(), "README.md");
+
+        const readme = generateReadme(file.getFilePath());
+
+        console.log(
+            chalk.gray("       Writing to", path.relative(__dirname, outPath))
+        );
+
+        await fs.writeFile(outPath, readme, { encoding: "utf-8" });
+    }
+
+    /*
+    const filename =
+        //   "./packages/unified-latex/unified-latex-types/index.ts";
+        "./packages/unified-latex/unified-latex-util-replace/index.ts";
+    //"./packages/unified-latex/unified-latex-util-trim/index.ts";
+    //"./packages/unified-latex/unified-latex-util-visit/index.ts";
+    */
+
+    function generateReadme(filename): string {
+        const sourceFile = project.getSourceFileOrThrow(filename);
+
+        const accumulatedExports = getDataOnAllExports(sourceFile);
+        const constantsMd = makeConstantsSection(accumulatedExports.constants);
+        const typesMd = makeTypesSection(accumulatedExports.types);
+        const funcsMd = makeFunctionsSection(accumulatedExports.funcs);
+        const pluginMd = makePluginsSection(accumulatedExports.plugins);
+
+        // Grab the comments from index.ts
+        const jsDoc = sourceFile.getLastToken().getFirstChild();
+        let introText = "";
+        if (Node.isJSDoc(jsDoc)) {
+            introText = jsDoc.getCommentText();
+        }
+
+        const directoryName = sourceFile.getDirectory().getBaseName();
+        let skeletonReadme = `# ${directoryName}`;
+        if (introText) {
+            skeletonReadme += "\n\n" + introText;
+        }
+        if (accumulatedExports.plugins.length > 0) {
+            skeletonReadme += "\n\n# Plugins";
+        }
+        if (accumulatedExports.funcs.length > 0) {
+            skeletonReadme += "\n\n# Functions";
+        }
+        if (accumulatedExports.constants.length > 0) {
+            skeletonReadme += "\n\n# Constants";
+        }
+        if (accumulatedExports.types.length > 0) {
+            skeletonReadme += "\n\n# Types";
+        }
+
+        // Assemble the dynamically-generated data
+        const target = gfmRemark.parse(skeletonReadme);
+
+        if (accumulatedExports.plugins.length > 0) {
+            inject("Plugins", target, pluginMd);
+        }
+        if (accumulatedExports.funcs.length > 0) {
+            inject("Functions", target, funcsMd);
+        }
+        if (accumulatedExports.constants.length > 0) {
+            inject("Constants", target, constantsMd);
+        }
+        if (accumulatedExports.types.length > 0) {
+            inject("Types", target, typesMd);
+        }
+
+        const renderedReadme = `${README_COMMENT}${gfmRemark.stringify(
+            target
+        )}`;
+
+        return renderedReadme;
+    }
+})();