Very rough generation of API documentation

Author: nojaf

.prettierrc.mjs

@@ -0,0 +1,13 @@
+/** @type {import("prettier").Config} */
+export default {
+    plugins: ["prettier-plugin-astro"],
+    overrides: [
+      {
+        files: "*.astro",
+        options: {
+          parser: "astro",
+        },
+      },
+    ],
+    endOfLine: "lf",
+  };

astro.config.mjs

@@ -1,38 +1,17 @@
 import { readFileSync } from "node:fs";
 import { defineConfig } from "astro/config";
 import starlight from "@astrojs/starlight";
-
-const starlightPlugin = {
-  name: "RescriptAPIDocs",
-  hooks: {
-    setup: ({ config, updateConfig, addIntegration }) => {
-      console.log(`Setup yow!`)
-      addIntegration({
-        name: "RescriptAPIDocs",
-        hooks: {
-          "astro:config:setup": ({ injectRoute }) => {
-            injectRoute({
-              pattern: "meh",
-              entrypoint: "docs/apidocs/meh.astro"
-            })
-          }
-        }
-      })
-
-      updateConfig({
-        sidebar: [
-          ...config.sidebar,
-          { label: "meh", link: "meh" }
-        ]
-      });
-    }
-  }
-}
+import { apiModules } from "./docs/pages/apidocs/utils";
 
 const rescriptTM = JSON.parse(
   readFileSync("./docs/assets/rescript.tmLanguage.json", "utf-8"),
 );
 
+const apiSidebarItems = apiModules.map(({ moduleName, link }) => ({
+  label: moduleName,
+  link,
+}));
+
 export default defineConfig({
   srcDir: "docs",
   publicDir: "docs/public",
@@ -45,24 +24,36 @@ export default defineConfig({
         src: "./docs/assets/rescript-logo.svg",
       },
       social: {
-        github: 'https://github.com/rescript-lang/experimental-rescript-webapi',
+        github: "https://github.com/rescript-lang/experimental-rescript-webapi",
       },
       editLink: {
-        baseUrl: 'https://github.com/rescript-lang/experimental-rescript-webapi/edit/main/',
+        baseUrl:
+          "https://github.com/rescript-lang/experimental-rescript-webapi/edit/main/",
       },
       sidebar: [
         {
-          slug: '',
+          slug: "",
+        },
+        {
+          slug: "design-philosophy",
         },
         {
-          slug: 'design-philosophy',
+          slug: "project-status",
         },
         {
-          slug: 'project-status',
+          label: "Contributing",
+          autogenerate: { directory: "contributing" },
         },
         {
-          label: 'Contributing',
-          autogenerate: { directory: 'contributing' },
+          label: "API Documentation",
+          collapsed: true,
+          items: [
+            {
+              label: "Overview",
+              link: "apidocs",
+            },
+            ...apiSidebarItems,
+          ],
         },
       ],
       customCss: ["./docs/styles/fonts.css", "./docs/styles/theme.css"],
@@ -71,7 +62,6 @@ export default defineConfig({
           langs: [rescriptTM],
         },
       },
-      plugins: [starlightPlugin],
     }),
   ],
 });

docs/apidocs/meh.astro

@@ -0,0 +1,38 @@
+---
+import { apiModules, getDoc } from "./utils";
+import StarlightPage from "@astrojs/starlight/components/StarlightPage.astro";
+
+export async function getStaticPaths() {
+  return apiModules.map((apiModule) => {
+    return {
+      params: {
+        API: apiModule.apiRoute,
+      },
+      props: apiModule,
+    };
+  });
+}
+
+const { moduleName, filePath } = Astro.props;
+
+const frontmatter = {
+  title: moduleName,
+};
+
+const headings = [
+  //   {
+  //     depth: 2,
+  //     slug: "web-apis",
+  //     text: "Web APIs",
+  //   },
+];
+
+const docInfo = await getDoc(filePath);
+---
+
+<StarlightPage frontmatter={frontmatter} headings={headings}>
+  <h2>{moduleName} overview</h2>
+  <code>
+    <pre>{JSON.stringify(docInfo, null, 4)}</pre>
+  </code>
+</StarlightPage>

docs/pages/apidocs/[API].astro

@@ -0,0 +1,31 @@
+---
+import StarlightPage from "@astrojs/starlight/components/StarlightPage.astro";
+import { apiModules } from "./utils";
+
+const frontmatter = {
+  title: "API Documentation",
+};
+
+const headings = [
+  {
+    depth: 2,
+    slug: "web-apis",
+    text: "Web APIs",
+  },
+];
+
+const resFiles = apiModules;
+---
+
+<StarlightPage frontmatter={frontmatter} headings={headings}>
+  <h2 id="web-apis">Web APIs</h2>
+  <ul>
+    {
+      resFiles.map(({ moduleName, link }) => (
+        <li>
+          <a href={link}>{moduleName}</a>
+        </li>
+      ))
+    }
+  </ul>
+</StarlightPage>

docs/pages/apidocs/index.astro

@@ -0,0 +1,47 @@
+import * as path from "node:path";
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+
+const execAsync = promisify(exec);
+
+function toKebabCase(input) {
+  return input
+    .replace(/([a-z])([A-Z])/g, "$1-$2") // Insert dash between lowercase and uppercase
+    .replace(/[\s_]+/g, "-") // Replace spaces or underscores with dash
+    .toLowerCase(); // Convert to lowercase
+}
+
+function mapRescriptFile(file) {
+  const moduleName = path
+    .basename(file, ".res")
+    .replace("$", "")
+    .replace("API", " API");
+  const link = `apidocs/${toKebabCase(moduleName)}`;
+  return {
+    filePath: path.join(import.meta.dirname, file),
+    moduleName,
+    link,
+    apiRoute: toKebabCase(moduleName),
+  };
+}
+
+export const apiModules = Object.keys(
+  import.meta.glob("../../../src/*.res"),
+).map(mapRescriptFile);
+
+export const fileModules = Object.keys(
+  import.meta.glob("../../../src/**/*.res"),
+).map(mapRescriptFile);
+
+export async function getDoc(absoluteFilePath) {
+  const { stdout, stderr } = await execAsync(
+    `rescript-tools doc ${absoluteFilePath}`,
+    {
+      maxBuffer: 1024 * 1024 * 10, // Increase buffer to 10 MB
+    },
+  );
+  if (stderr) {
+    throw new Error(stderr);
+  }
+  return JSON.parse(stdout);
+}

docs/pages/apidocs/utils.js

@@ -29,18 +29,19 @@
   "scripts": {
     "test": "node tests/index.js",
     "build": "rewatch",
-    "format": "rescript format -all && prettier --write ./tests/index.js ./package.json",
+    "format": "rescript format -all && prettier --write ./tests/index.js ./package.json ./docs/pages",
     "docs": "astro dev",
     "build:docs": "astro build"
   },
   "license": "MIT",
   "dependencies": {
-    "rescript": "^12.0.0-alpha.4"
+    "rescript": "^12.0.0-alpha.5"
   },
   "devDependencies": {
     "@astrojs/starlight": "^0.29.0",
     "astro": "^4.16.10",
     "prettier": "^3.3.3",
+    "prettier-plugin-astro": "^0.14.1",
     "sharp": "^0.33.5"
   }
 }