Generate pages and sidebar directly in Vitepress

.earthlyignore

@@ -1,5 +1,3 @@
 docs/node_modules
 docs/.vitepress/dist
 docs/.vitepress/cache
-docs/.vitepress/reference-sidebar.autogenerated.ts
-docs/reference/*

.gitignore

@@ -3,3 +3,4 @@ dump/
 examples/**/*.lua
 *.zip
 .tmp-earthly-out
+**/classes.xml

Earthfile

@@ -38,19 +38,18 @@ build-examples:
     COPY src src
     RUN deno run --allow-run=haxe --allow-read=examples scripts/build-examples.ts
 
-build-docs-generate-reference:
+build-docs-dump-types:
 
     FROM +setup-deno
 
-    RUN mkdir docs && mkdir docs/.vitepress && mkdir docs/reference
+    RUN mkdir docs && mkdir docs/reference
     COPY scripts scripts
     COPY src src
     RUN deno run --allow-run --allow-read=docs --allow-write=docs scripts/generate-class-reference.ts
 
-    # These artifacts do not have to be local to build the final HTML version,
-    # but we can use them for hot-reloading a dev server on a host machine (vitepress dev docs)
-    SAVE ARTIFACT docs/.vitepress/reference-sidebar.autogenerated.ts AS LOCAL docs/.vitepress/reference-sidebar.autogenerated.ts
-    SAVE ARTIFACT docs/reference/minetest AS LOCAL docs/reference/minetest
+    # This artifact does not have to be local to build the final HTML version,
+    # but we can use it for hot-reloading a dev server on a host machine (vitepress dev docs)
+    SAVE ARTIFACT docs/reference/generation/classes.xml AS LOCAL docs/reference/generation/classes.xml
 
 build-docs-static-html:
 
@@ -65,11 +64,10 @@ build-docs-static-html:
 
     # Build Vitepress site
     COPY docs .
-    COPY +build-docs-generate-reference/reference-sidebar.autogenerated.ts .vitepress/reference-sidebar.autogenerated.ts
-    COPY +build-docs-generate-reference/minetest reference/minetest
+    COPY +build-docs-dump-types/classes.xml reference/generation/classes.xml
     RUN deno run -A npm:vitepress build .
     SAVE ARTIFACT .vitepress/dist AS LOCAL docs/.vitepress/dist
 
 build-docs:
-    BUILD +build-docs-generate-reference
+    BUILD +build-docs-dump-types
     BUILD +build-docs-static-html

docs/.vitepress/config.ts

@@ -1,5 +1,5 @@
 import { defineConfig } from 'vitepress'
-import referenceSidebar from './reference-sidebar.autogenerated'
+import referenceSidebar from '../reference/generation/sidebar'
 
 // https://vitepress.dev/reference/site-config
 
@@ -18,7 +18,7 @@ export default defineConfig({
     // https://vitepress.dev/reference/default-theme-config
     nav: [
       { text: 'Guide', link: '/guide/getting-started' },
-      { text: 'Reference', link: '/reference/minetest/Minetest' }
+      { text: 'Reference', link: '/reference/minetest.Minetest' }
     ],
 
     sidebar: {
@@ -46,5 +46,7 @@ export default defineConfig({
     socialLinks: [
       { icon: 'github', link: 'https://github.com/frixuu/hxminetest/' }
     ]
-  }
+  },
+
+
 })

docs/package.json

@@ -2,6 +2,7 @@
   "type": "module",
   "devDependencies": {
     "@lowlighter/xml": "^5.4.12",
+    "@types/node": "20",
     "sass": "^1.77.8",
     "vitepress": "^1.3.1",
     "vue": "^3.4.33"

docs/reference/[type].paths.ts

@@ -0,0 +1,14 @@
+import { data as typeDefs } from "./generation/rtti.data";
+
+export default {
+
+  async paths() {
+
+    return typeDefs.map(def => {
+      return {
+        params: { type: def.path.toString(), },
+        content: def.renderMarkdownReference(),
+      }
+    });
+  }
+}

docs/reference/generation/rtti.data.ts

@@ -1,14 +1,18 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
 import { defineLoader } from "vitepress";
 import { Definition } from "./definition";
 import { parseRttiXml } from "./parse";
 
-declare const data: Definition[];
+const RTTI_PATH = join(import.meta.dirname, "classes.xml");
+const READ_OPTS = { encoding: "utf-8" } as const;
+
+const data: Definition[] = parseRttiXml(await readFile(RTTI_PATH, READ_OPTS));
 export { data };
 
 export default defineLoader({
-  watch: ["../classes.xml"],
+  watch: [RTTI_PATH],
   async load(watchedFiles): Promise<Definition[]> {
-    const file = await Deno.readTextFile(watchedFiles[0]);
-    return parseRttiXml(file);
+    return parseRttiXml(await readFile(watchedFiles[0], READ_OPTS));
   }
 });

docs/reference/generation/sidebar.ts

@@ -0,0 +1,65 @@
+import type { DefaultTheme } from "vitepress";
+import { Definition } from "./definition";
+import { data as typeDefs } from "./rtti.data";
+
+// The types are currently stored in a flat structure.
+// We want subpackages to be collapsible items on the sidebar,
+// so we need to build a tree to generate it.
+
+interface PackageTreeNode {
+  currentPath: string[];
+  subpackages: Map<string, PackageTreeNode>;
+  directTypes: Definition[];
+}
+
+const sidebarRoot: PackageTreeNode = {
+  currentPath: [],
+  subpackages: new Map(),
+  directTypes: [],
+}
+
+for (const typeDef of typeDefs) {
+  let root = sidebarRoot;
+  let pack = typeDef.path.pack;
+  const pathSoFar: string[] = [];
+  while (pack.length > 0) {
+    const nextSubpackage = pack[0];
+    pathSoFar.push(nextSubpackage);
+    pack = pack.slice(1);
+    let child = root.subpackages.get(nextSubpackage);
+    if (child === undefined) {
+      child = { currentPath: pathSoFar, subpackages: new Map(), directTypes: [] };
+      root.subpackages.set(nextSubpackage, child);
+    }
+    root = child;
+  }
+  root.directTypes.push(typeDef);
+}
+
+type SidebarItem = DefaultTheme.SidebarItem;
+
+function buildLeaf(def: Definition): SidebarItem {
+  return {
+    text: def.path.shortName(),
+    link: `/reference/${def.path.toString()}`
+  };
+}
+
+function buildNode(el: PackageTreeNode): SidebarItem {
+  return {
+    text: el.currentPath.at(-1),
+    collapsed: true,
+    items: buildEdges(el),
+  };
+}
+
+function buildEdges(el: PackageTreeNode): SidebarItem[] {
+  const children = Array.from(el.subpackages.values()).map(p => buildNode(p));
+  const types = el.directTypes.map(t => buildLeaf(t));
+  return children.concat(types);
+}
+
+const sidebar = buildEdges(sidebarRoot);
+sidebar[0].collapsed = false;
+
+export default sidebar;