From 4e7b39b9318f7c594dd1dc21d4489d286eeadb0a Mon Sep 17 00:00:00 2001
From: Loren Norman <lorennorman@gmail.com>
Date: Thu, 12 Jun 2025 12:26:45 -0400
Subject: [PATCH] initial doc generation script

---
 docs/.vitepress/config.js | 22 ++++++++---
 export_documentation.js   | 79 +++++++++++++++++++++++++++++++++++++++
 package.json              |  1 +
 3 files changed, 97 insertions(+), 5 deletions(-)
 create mode 100644 export_documentation.js

diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js
index 4d9b6e9..51cb841 100644
--- a/docs/.vitepress/config.js
+++ b/docs/.vitepress/config.js
@@ -1,11 +1,23 @@
 import { defineConfig } from 'vitepress'
 
+
+const REPO = 'https://github.com/lorennorman/blockly-tool'
+
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
   title: "IO Actions: Block Reference",
   description: "Documentation for Adafruit IO's block-based Actions",
+
+  // https://vitepress.dev/reference/default-theme-config
   themeConfig: {
-    // https://vitepress.dev/reference/default-theme-config
+    editLink: {
+      pattern: ({ filePath }) => {
+        const jsPath = filePath.replace(/.md$/, '.js')
+
+        return `https://github.com/lorennorman/blockly-tool/edit/main/app/${jsPath}`
+      }
+    },
+
     nav: [
       { text: 'Home', link: '/' },
       { text: 'Examples', link: '/markdown-examples' }
@@ -13,16 +25,16 @@ export default defineConfig({
 
     sidebar: [
       {
-        text: 'Examples',
+        text: 'Blocks',
         items: [
-          { text: 'Markdown Examples', link: '/markdown-examples' },
-          { text: 'Runtime API Examples', link: '/api-examples' }
+          { text: 'Email', link: '/blocks/action/email' },
+          { text: 'Log', link: '/blocks/action/log' }
         ]
       }
     ],
 
     socialLinks: [
-      { icon: 'github', link: 'https://github.com/vuejs/vitepress' }
+      { icon: 'github', link: REPO }
     ]
   }
 })
diff --git a/export_documentation.js b/export_documentation.js
new file mode 100644
index 0000000..eeeb64f
--- /dev/null
+++ b/export_documentation.js
@@ -0,0 +1,79 @@
+import fs from 'fs'
+
+// make a tiny DSL
+const withCleanDir = async (dirName, writeFunction) => {
+  const startTime = Date.now()
+  console.log("Starting Documentation Export")
+  console.log("=======================")
+
+  if(fs.existsSync(dirName)) {
+    fs.rmSync(dirName, { recursive: true, force: true })
+  }
+  fs.mkdirSync(dirName)
+  console.log(`/${dirName}: clean`)
+
+  let totalBytesWritten = 0
+  const write = (filename, fileContents) => {
+    const
+      exportFilename = `${dirName}/${filename}`,
+      exportDirname = exportFilename.split("/").slice(0, -1).join("/"),
+      bytesToWrite = fileContents.length/1000
+
+    // ensure dir is present before writing
+    if(!fs.existsSync(exportDirname)) {
+      console.log("mkdir:", exportDirname)
+      fs.mkdirSync(exportDirname, { recursive: true })  
+    }
+
+    // write the file
+    fs.writeFileSync(exportFilename, fileContents)
+
+    // log and remember
+    // console.log(`/${exportFilename} (${bytesToWrite}k)`)
+    totalBytesWritten += bytesToWrite
+  }
+
+  await writeFunction(write)
+
+  const elapsed = Date.now() - startTime
+  console.log("=======================")
+  console.log(`🏁 Done. Wrote ${totalBytesWritten.toString().slice(0,5)}k in ${elapsed}ms 🏁`)
+}
+
+import { importBlockJson, importBlockDefinitions, allBlockDefinitionsAndPaths } from './src/importer/block_importer.js'
+import importToolboxJson from './src/importer/toolbox_importer.js'
+import importWorkspaceJson from './src/importer/workspace_importer.js'
+import importBlocklyJs from './src/importer/blockly_importer.js'
+import { map } from 'lodash-es'
+
+
+
+const toBlockMarkdown = definition => {
+  return `---
+title: "Block: ${definition.type}"
+editLink: true
+---
+${ definition.visualization?.tooltip || "No docs for this block, yet." }
+`
+}
+
+withCleanDir("docs/blocks", async write => {
+  map(allBlockDefinitionsAndPaths, ({ path, definition }) => {
+    // skip disabled blocks
+    if(definition.disabled) { return }
+
+    const blockKey = definition.type
+
+    // mirror the blocks/**/*.js path structure
+    const docPath = path.replace(/.js$/, '.md')
+    // console.log(blockKey, docPath)
+    write(docPath, toBlockMarkdown(definition))
+    // console.log(key, Object.keys(definition))
+  })
+  // write("blocks.json", pretty(await importBlockJson()))
+  // write("toolbox.json", pretty(await importToolboxJson()))
+  // write("workspace.json", pretty(await importWorkspaceJson()))
+
+  // // JS
+  // write("blockly.js", await importBlocklyJs())
+})
diff --git a/package.json b/package.json
index f792cde..f7f186d 100644
--- a/package.json
+++ b/package.json
@@ -19,6 +19,7 @@
     "build-all-branches": "node build_all_branches.js",
     "preview": "npm run build && vite preview",
     "export": "node export.js",
+    "docs:export": "node export_documentation.js",
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
     "docs:preview": "vitepress preview docs"