Fully generate snippet docs

Author: matijaoe

README.md

@@ -1,7 +1,10 @@
 import { parse } from "./deps.ts";
-import { VscSnippetDefinition } from "./models/app.ts";
-import { variants } from "./snippets/app.ts";
-import { logTables } from "./utils/markdown.ts";
+import {
+  generateSnippetDocs,
+  generateVariantSections,
+} from "./docs-gen/snippets.ts";
+// import { logMdTables } from "./docs-gen/table-md.ts";
+import { languages } from "./snippets/app.ts";
 import {
   convertToVscSnippet,
   generateSnippetsFile,
@@ -16,23 +19,26 @@ const flags = parse(Deno.args, {
 if (!flags.table && !flags.snippets) {
   console.log("Please specify at least one flag: --table or --snippets");
 } else {
-  variants.forEach((variant) => {
-    const categorizedVscSnippets: VscSnippetDefinition[] = variant
-      .snippetsWithMeta.map(
-        (item) => ({
-          ...item,
-          snippets: convertToVscSnippet(item.snippets),
-        }),
-      );
+  if (flags.snippets) {
+    // Snippets generation
+    languages.forEach((language) => {
+      const categorizedVscSnippets = language
+        .snippetDefinitions.map(
+          (item) => ({
+            ...item,
+            snippets: convertToVscSnippet(item.snippets),
+          }),
+        );
 
-    if (flags.table) {
-      logTables(variant.label, categorizedVscSnippets);
-    }
-    if (flags.snippets) {
       const variantVscSnippet = groupSnippets(
         categorizedVscSnippets.map((item) => item.snippets),
       );
-      generateSnippetsFile(variant.extension, variantVscSnippet);
-    }
-  });
+      generateSnippetsFile(language.fileExtension, variantVscSnippet);
+    });
+  }
+
+  if (flags.table) {
+    const sections = generateVariantSections(languages);
+    generateSnippetDocs(sections);
+  }
 }

src/app.ts

@@ -0,0 +1,73 @@
+import { ensureDirSync } from "../deps.ts";
+import { XSnippetDefinition, XSnippetVariant } from "../models/app.ts";
+import {
+  $col,
+  $colCode,
+  $colCodeBlock,
+  $row,
+  $table,
+  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 generateVariantSections = (variants: XSnippetVariant[]) => {
+  return joinByDoubleNewLine(variants.map(generateVariantSection));
+};
+
+export const generateSnippetDocs = (table: string) => {
+  const path = "./dist";
+  ensureDirSync(path);
+  const file = `${path}/docs.md`;
+
+  Deno.writeFileSync(
+    file,
+    new TextEncoder().encode(table),
+  );
+};

src/docs-gen/snippets.ts

@@ -0,0 +1,52 @@
+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 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}\``;
 
@@ -14,6 +14,7 @@ export const serializeForMarkdown = (str: string) => {
       .replace(/\|/g, "\\|");
   }
   // TODO: dont remove | when it is in ``
+  // but it's different 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,
   },
 ];