Populate generated docs into readme

Author: matijaoe

README.md

@@ -354,14 +354,13 @@ Will be sorted into appropriate categories in the future.
 # ensure Deno is installed
 # https://deno.land/manual@v1.29.1/getting_started/installation
 
-# generate .code-snippets
+# generate .code-snippets and documentation
 npm run generate
 ```
 
 ---
 
-## 🚧 Experimental documentation
-
+<!-- START:docs-gen -->
 ## Snippets
 
 
@@ -3589,3 +3588,5 @@ type ${1:Model} = ${2:first} & ${3:second}
 </td>
 </tr>
 </table>
+
+<!-- END:docs-gen -->

package.json

@@ -38,10 +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",
-    "test": "deno run --allow-write --allow-read src/utils/table.ts"
+    "generate": "deno run -A src/app.ts --snippets --docs",
+    "generate:snippets": "deno run -A src/app.ts --snippets"
   },
   "contributes": {
     "snippets": [

src/app.ts

@@ -1,44 +1,41 @@
 import { parse } from "./deps.ts";
-import {
-  generateSnippetDocs,
-  generateVariantSections,
-} from "./docs-gen/snippets.ts";
-// import { logMdTables } from "./docs-gen/table-md.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 {
   if (flags.snippets) {
-    // Snippets generation
     languages.forEach((language) => {
       const categorizedVscSnippets = language
         .snippetDefinitions.map(
-          (item) => ({
-            ...item,
-            snippets: convertToVscSnippet(item.snippets),
-          }),
+          (item) => {
+            const snippets = convertToVscSnippet(item.snippets);
+            return { ...item, snippets };
+          },
         );
 
       const variantVscSnippet = groupSnippets(
         categorizedVscSnippets.map((item) => item.snippets),
       );
-      generateSnippetsFile(language.fileExtension, variantVscSnippet);
+      generateSnippets(language.fileExtension, variantVscSnippet);
     });
   }
 
-  if (flags.table) {
-    const sections = generateVariantSections(languages);
-    generateSnippetDocs(sections);
+  // TODO: probably better to make it generate from vsc json
+  // pass in meta, and snippets converted to vsc format
+  if (flags.docs) {
+    const docs = generateDocs(languages);
+    populateDocsBlock(docs);
   }
 }

src/deps.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/docs-gen/snippets.ts

@@ -1,11 +1,12 @@
-import { ensureDirSync } from "../deps.ts";
+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";
@@ -57,17 +58,36 @@ const generateVariantSection = (variant: XSnippetVariant) => {
   return joinByNewLine([title, description, "", ...sections]);
 };
 
-export const generateVariantSections = (variants: XSnippetVariant[]) => {
+export const generateDocs = (variants: XSnippetVariant[]) => {
   return joinByDoubleNewLine(variants.map(generateVariantSection));
 };
 
-export const generateSnippetDocs = (table: string) => {
-  const path = "./dist";
-  ensureDirSync(path);
-  const file = `${path}/docs.md`;
+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]);
+};
 
-  Deno.writeFileSync(
-    file,
-    new TextEncoder().encode(table),
+export const populateDocsBlock = async (input: string) => {
+  const regex = new RegExp(
+    `${docsGen.start}[\\s\\S]*?${docsGen.end}`,
+    "g",
   );
+
+  const options = {
+    files: "./README.md",
+    from: regex,
+    to: docsBlock(input),
+  };
+
+  try {
+    const results = await replaceInFile(options);
+    console.log("Replacement results:", results);
+  } catch (error) {
+    console.error("Error occurred:", error);
+  }
 };

src/docs-gen/table-html.ts

@@ -4,6 +4,7 @@ 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 + "`");
 };

src/docs-gen/table-md.ts

@@ -13,8 +13,8 @@ export const serializeForMarkdown = (str: string) => {
       .replace(/\t/g, "  ")
       .replace(/\|/g, "\\|");
   }
-  // TODO: dont remove | when it is in ``
-  // but it's different for every .md implementation
+  // TODO: don't remove | when it is in code block
+  // but it differs for every .md implementation
   return str.replace(/\|/g, "\\|");
 };
 

src/utils/snippets.ts

@@ -17,7 +17,7 @@ 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`;