Add examples

Author: nojaf

astro.config.mjs

@@ -51,6 +51,10 @@ export default defineConfig({
         {
           slug: "design-philosophy",
         },
+        {
+          label: "Examples",
+          link: "examples",
+        },
         {
           slug: "project-status",
         },

docs/pages/examples.astro

@@ -0,0 +1,56 @@
+---
+import StarlightPage from "@astrojs/starlight/components/StarlightPage.astro";
+import { Tabs, TabItem, Code } from "@astrojs/starlight/components";
+import { testFiles } from "../utils";
+
+const frontmatter = {
+  title: "Examples",
+};
+
+const headings = testFiles.map(({ name }) => ({
+  depth: 2,
+  slug: name,
+  text: name,
+}));
+---
+
+<StarlightPage frontmatter={frontmatter} headings={headings}>
+  <p>
+    The best example of usage of these bindings are the <a href="./06-testing"
+      >tests</a
+    >. <br />
+    These typically contain tweaks made to the generated bindings to make them more
+    ergonomic.
+  </p>
+  {
+    testFiles.map(({ source, output, name }) => {
+      return (
+        <div class="example" id={name}>
+          <h2>{name}</h2>
+          <Tabs>
+            <TabItem label="ReScript">
+              <Code code={source} lang="ReScript" frame="none" />
+            </TabItem>
+            <TabItem label="JS Output">
+              <Code code={output} lang="js" frame="none" />
+            </TabItem>
+          </Tabs>
+        </div>
+      );
+    })
+  }
+</StarlightPage>
+<style>
+  .example {
+    margin-block: 4rem;
+
+    &:first-of-type {
+      margin-top: 4rem;
+    }
+
+    & h2 {
+      margin-bottom: 1rem;
+      font-size: var(--sl-text-2xl);
+    }
+  }
+</style>

docs/utils.js

@@ -1,7 +1,7 @@
 import * as path from "node:path";
 import { exec } from "node:child_process";
 import { promisify } from "node:util";
-import { readdirSync, existsSync } from "fs";
+import { readdirSync, existsSync, readFileSync } from "fs";
 import { micromark } from "micromark";
 
 const execAsync = promisify(exec);
@@ -140,4 +140,34 @@ export async function getDoc(absoluteFilePath) {
     values,
     valueHeadings,
   };
-}
+}
+
+function trimRescriptOutput(output) {
+  return output
+    .replace("// Generated by ReScript, PLEASE EDIT WITH CARE", "")
+    .replace("/* response Not a pure module */", "")
+    .trim();
+}
+
+const testDir = path.resolve(process.cwd(), "tests");
+export const testFiles =
+  readdirSync(testDir, { recursive: true })
+    .filter(f => f.endsWith(".res"))
+    .map(tf => {
+      const sourcePath = path.join(testDir, tf);
+      const source = readFileSync(sourcePath, "utf-8");
+      const outputPath = sourcePath.replace(".res", ".js");
+      const output = readFileSync(outputPath, "utf-8");
+
+      const parts = tf.split(path.sep);
+      const name = parts[parts.length - 1].replace("__tests.res", "");
+
+      return {
+        sourcePath: sourcePath.replace(testDir,""),
+        source,
+        output: trimRescriptOutput(output),
+        outputPath: outputPath.replace(testDir,""),
+        name,
+      };
+    })
+    .sort((a, b) => a.name.localeCompare(b.name));