Auto-generate docs

Feature/generate html tables

Author: matijaoe

README.md

@@ -38,9 +38,8 @@
   },
   "scripts": {
     "publish": "vsce package && vsce publish",
-    "generate": "deno run --allow-write --allow-read src/app.ts",
-    "generate:table": "deno run --allow-write --allow-read src/app.ts --table --snippets=false",
-    "generate:all": "deno run --allow-write --allow-read src/app.ts --table --snippets"
+    "generate": "deno run -A src/app.ts --snippets --docs",
+    "generate:snippets": "deno run -A src/app.ts --snippets"
   },
   "contributes": {
     "snippets": [

package.json

@@ -1,38 +1,43 @@
 import { parse } from "./deps.ts";
-import { VscSnippetDefinition } from "./models/app.ts";
-import { variants } from "./snippets/app.ts";
-import { logTables } from "./utils/markdown.ts";
+import { generateDocs, populateDocsBlock } from "./docs-gen/snippets.ts";
+import { languages } from "./snippets/app.ts";
 import {
   convertToVscSnippet,
-  generateSnippetsFile,
+  generateSnippets,
   groupSnippets,
 } from "./utils/snippets.ts";
 
 const flags = parse(Deno.args, {
-  boolean: ["table", "snippets"],
-  default: { snippets: true },
+  boolean: ["snippets", "docs"],
+  default: { snippets: false, docs: false },
 });
 
-if (!flags.table && !flags.snippets) {
-  console.log("Please specify at least one flag: --table or --snippets");
+if (!flags.snippets && !flags.docs) {
+  console.log("Please specify at least one flag: --snippets or --docs");
 } else {
-  variants.forEach((variant) => {
-    const categorizedVscSnippets: VscSnippetDefinition[] = variant
-      .snippetsWithMeta.map(
-        (item) => ({
-          ...item,
-          snippets: convertToVscSnippet(item.snippets),
-        }),
-      );
+  if (flags.snippets) {
+    console.log("\nGenerating snippets...");
+    languages.forEach((language) => {
+      const categorizedVscSnippets = language
+        .snippetDefinitions.map(
+          (item) => {
+            const snippets = convertToVscSnippet(item.snippets);
+            return { ...item, snippets };
+          },
+        );
 
-    if (flags.table) {
-      logTables(variant.label, categorizedVscSnippets);
-    }
-    if (flags.snippets) {
       const variantVscSnippet = groupSnippets(
         categorizedVscSnippets.map((item) => item.snippets),
       );
-      generateSnippetsFile(variant.extension, variantVscSnippet);
-    }
-  });
+      generateSnippets(language.fileExtension, variantVscSnippet);
+    });
+  }
+
+  // TODO: probably better to make it generate from vsc json
+  // pass in meta, and snippets converted to vsc format
+  if (flags.docs) {
+    console.log("\nGenerating docs...");
+    const docs = generateDocs(languages);
+    populateDocsBlock(docs);
+  }
 }

src/app.ts

@@ -1,3 +1,10 @@
-export { parse } from "https://deno.land/std@0.168.0/flags/mod.ts";
 export { ensureDirSync } from "https://deno.land/std@0.141.0/fs/ensure_dir.ts";
+export { parse } from "https://deno.land/std@0.168.0/flags/mod.ts";
 export { markdownTable } from "https://esm.sh/markdown-table@3";
+
+import replace, * as _replace from "npm:replace-in-file";
+
+// Fix types
+export const replaceInFile = replace as unknown as (
+  config: _replace.ReplaceInFileConfig,
+) => Promise<_replace.ReplaceResult[]>;

src/deps.ts

@@ -0,0 +1,100 @@
+import { replaceInFile } from "../deps.ts";
+import { XSnippetDefinition, XSnippetVariant } from "../models/app.ts";
+import {
+  $col,
+  $colCode,
+  $colCodeBlock,
+  $row,
+  $table,
+  htmlComment,
+  joinByDoubleNewLine,
+  joinByNewLine,
+} from "./table-html.ts";
+
+type SnippetRow = {
+  prefix: string;
+  name: string;
+  body: string | string[];
+};
+
+const snippetRow = ({ prefix, name, body }: SnippetRow) => {
+  const parsedBody = Array.isArray(body) ? body.join("\n") : body;
+  const cols = joinByNewLine([
+    $colCode(prefix),
+    $col(name),
+    $colCodeBlock(parsedBody),
+  ]);
+
+  return $row(cols);
+};
+
+const generateSnippetTable = (items: SnippetRow[]) => {
+  const headings = ["Prefix", "Name", "Body"];
+  const rows = items.map(snippetRow);
+
+  return $table(headings, rows);
+};
+
+const generateSnippetSection = (
+  { meta, snippets }: XSnippetDefinition,
+) => {
+  const title = `### ${meta.title}`;
+  const description = meta.description ?? "";
+  const table = generateSnippetTable(
+    Object.entries(snippets).map(([prefix, value]) => ({
+      ...value,
+      prefix,
+    })),
+  );
+
+  return joinByNewLine([title, description, table, ""]);
+};
+
+const generateVariantSection = (variant: XSnippetVariant) => {
+  const title = `## ${variant.label}`;
+  const description = variant.description ?? "";
+  const sections = variant.snippetDefinitions.map(generateSnippetSection);
+
+  return joinByNewLine([title, description, "", ...sections]);
+};
+
+export const generateDocs = (variants: XSnippetVariant[]) => {
+  return joinByDoubleNewLine(variants.map(generateVariantSection));
+};
+
+const docsGenId = "docs-gen";
+const docsGen = {
+  start: htmlComment(`START:${docsGenId}`),
+  end: htmlComment(`END:${docsGenId}`),
+};
+
+const docsBlock = (s: string) => {
+  return joinByNewLine([docsGen.start, s, docsGen.end]);
+};
+
+export const populateDocsBlock = async (input: string) => {
+  const regex = new RegExp(
+    `${docsGen.start}[\\s\\S]*?${docsGen.end}`,
+    "g",
+  );
+
+  const file = "./README.md";
+  const options = {
+    files: file,
+    from: regex,
+    to: docsBlock(input),
+  };
+
+  try {
+    const results = await replaceInFile(options);
+    const readmeResult = results.find((r) => r.file === file);
+
+    if (readmeResult?.hasChanged) {
+      console.log("✅ README updated");
+    } else {
+      console.log("👍 README already up to date");
+    }
+  } catch (error) {
+    console.error("Error while updating README:", error);
+  }
+};

src/docs-gen/snippets.ts

@@ -0,0 +1,53 @@
+export const joinInline = (s: string[]) => s.join("");
+export const joinByNewLine = (s: string[]) => s.join("\n");
+export const joinByDoubleNewLine = (s: string[]) => s.join("\n\n");
+export const indent = (s: string, size = 2) => `${" ".repeat(size)}${s}`;
+export const escapeBackticks = (s: string) => s.replace(/`/g, "\`");
+
+export const htmlComment = (s: string) => `<!-- ${s} -->`;
+export const code = (s: string) => {
+  return escapeBackticks("`" + s + "`");
+};
+
+export const codeBlock = (s: string, lang = "javascript") => {
+  return joinByNewLine([
+    `${indent(escapeBackticks("```" + lang))}`,
+    s,
+    `${indent(escapeBackticks("```"))}`,
+  ]);
+};
+
+export const $row = (s: string) => {
+  return joinByNewLine(["", "<tr>", s, "</tr>"]);
+};
+
+export const $colDoubleNewLine = (
+  s: string,
+  cb?: (input: string) => string,
+) => {
+  return joinByDoubleNewLine(["<td>", cb?.(s) ?? s, "</td>"]);
+};
+
+export const $col = (s: string) => {
+  return `<td>${s}</td>`;
+};
+export const $colCode = (s: string) => {
+  return $colDoubleNewLine(s, code);
+};
+export const $colCodeBlock = (s: string) => {
+  return $colDoubleNewLine(s, codeBlock);
+};
+
+export const $headerRow = (headers: string[]) => {
+  const cols = joinByNewLine(headers.map($col));
+  return $row(cols);
+};
+
+export const $table = (headings: string[], rows: string[]) => {
+  return joinByNewLine([
+    "<table>",
+    $headerRow(headings),
+    joinByNewLine(rows),
+    "</table>",
+  ]);
+};

src/docs-gen/table-html.ts

@@ -1,6 +1,6 @@
-import { VscSnippetDefinition, VscSnippetDict } from "../models/app.ts";
 import { markdownTable } from "../deps.ts";
-import { replaceSymbol } from "./general.ts";
+import { VscSnippetDefinition, VscSnippetDict } from "../models/app.ts";
+import { replaceSymbol } from "../utils/general.ts";
 
 export const code = (str: string) => `\`${str}\``;
 
@@ -13,7 +13,8 @@ export const serializeForMarkdown = (str: string) => {
       .replace(/\t/g, "  ")
       .replace(/\|/g, "\\|");
   }
-  // TODO: dont remove | when it is in ``
+  // TODO: don't remove | when it is in code block
+  // but it differs for every .md implementation
   return str.replace(/\|/g, "\\|");
 };
 

src/utils/markdown.ts renamed to src/docs-gen/table-md.ts

@@ -19,3 +19,11 @@ export type GenericSnippetDictWithMeta<T> = {
 };
 export type XSnippetDefinition = GenericSnippetDictWithMeta<XSnippetDict>;
 export type VscSnippetDefinition = GenericSnippetDictWithMeta<VscSnippetDict>;
+
+export type XSnippetVariant = {
+  label: string;
+  description?: string;
+  language: string;
+  fileExtension: string;
+  snippetDefinitions: XSnippetDefinition[];
+};

src/models/app.ts

@@ -1,24 +1,19 @@
-import { XSnippetDefinition } from "../models/app.ts";
+import { XSnippetVariant } from "../models/app.ts";
 import { javascript } from "./js/app.ts";
 import { typescript } from "./ts/app.ts";
 
-type SnippetVariant = {
-  label: string;
-  language: string;
-  extension: string;
-  snippetsWithMeta: XSnippetDefinition[];
-};
-export const variants: SnippetVariant[] = [
+export const languages: XSnippetVariant[] = [
   {
     label: "Snippets",
     language: "javascript",
-    extension: "js",
-    snippetsWithMeta: javascript,
+    fileExtension: "js",
+    snippetDefinitions: javascript,
   },
   {
     label: "TypeScript specific",
+    description: "Only applied to .ts and .tsx files",
     language: "typescript",
-    extension: "ts",
-    snippetsWithMeta: typescript,
+    fileExtension: "ts",
+    snippetDefinitions: typescript,
   },
 ];

src/snippets/app.ts

@@ -17,13 +17,21 @@ export const groupSnippets = (dicts: VscSnippetDict[]) => {
   }));
 };
 
-export const generateSnippetsFile = (name: string, data: VscSnippetDict) => {
+export const generateSnippets = (name: string, data: VscSnippetDict) => {
   const path = "./dist";
-  ensureDirSync(path);
-  const file = `${path}/${name}.code-snippets`;
+  const fileName = `${name}.code-snippets`;
+  try {
+    ensureDirSync(path);
+    const file = `${path}/${fileName}`;
 
-  Deno.writeTextFileSync(
-    file,
-    JSON.stringify(data, null, 2),
-  );
+    Deno.writeTextFileSync(
+      file,
+      JSON.stringify(data, null, 2),
+    );
+
+    console.log(`✅ ${fileName}`);
+  } catch (error) {
+    console.log(`❌ ${fileName}`);
+    console.error(error);
+  }
 };