Complete signature details of values

nojaf · nojaf · commit 8cf82884e32c · 2024-11-23T14:30:46.000+01:00
diff --git a/astro.config.mjs b/astro.config.mjs
@@ -1,13 +1,13 @@
 import { readFileSync } from "node:fs";
 import { defineConfig } from "astro/config";
 import starlight from "@astrojs/starlight";
-import { apiModules } from "./docs/pages/apidocs/utils";
+import { apiModules } from "./docs/utils";
 
 const rescriptTM = JSON.parse(
   readFileSync("./docs/assets/rescript.tmLanguage.json", "utf-8"),
 );
 
-const apiSidebarItems = apiModules.map(({ moduleName, link, items }) => {
+const apiSidebarItems  = apiModules.map(({ moduleName, link, items }) => {
   const nestedItems = Object.values(items).map(({ moduleName, link }) => ({
     label: moduleName,
     link
diff --git a/docs/components/record.astro b/docs/components/record.astro
@@ -31,7 +31,6 @@ const { name, items, typesInOwnModule } = Astro.props;
     grid-template-rows: repeat(2, auto);
     grid-template-columns: repeat(2, 1fr);
     gap: 0.5rem;
-
     border-bottom: 1px solid var(--sl-color-gray-7);
 
     & .type {
diff --git a/docs/components/signature.astro b/docs/components/signature.astro
@@ -15,20 +15,20 @@ function parseTokens(tokens) {
   let index = 0;
 
   const parseNode = () => {
-    const ident = tokens[index++]; // Read the current token and increment index
-    let genericArguments = [];
+    const path = tokens[index++]; // Read the current token and increment index
+    let genericTypeParameters = [];
 
     if (tokens[index] === "<") {
       // Check for generics
       index++; // Consume "<"
       while (tokens[index] !== ">") {
-        genericArguments.push(parseNode());
+        genericTypeParameters.push(parseNode());
         if (tokens[index] === ",") index++; // Consume ","
       }
       index++; // Consume ">"
     }
 
-    return { ident, genericArguments };
+    return { path, genericTypeParameters };
   };
 
   return parseNode();
diff --git a/docs/components/signatureItem.astro b/docs/components/signatureItem.astro
@@ -1,29 +1,38 @@
 ---
-import { createModuleLink } from "../pages/apidocs/utils.js";
+import { createAPIModuleLink } from "../utils.js";
 const { item, typesInOwnModule } = Astro.props;
 
 let link;
-if (typesInOwnModule.has(item.ident)) {
-  link = `#${item.ident}`;
+if (typesInOwnModule && typesInOwnModule.has(item.path)) {
+  link = `#${item.path}`;
 }
 
-if (item.ident.startsWith("WebAPI.")) {
-  const idents = item.ident.split(".");
-  if (idents.length === 3){
-    link = `${createModuleLink(idents[1])}#${idents[2]}`;
+if (item.path.startsWith("WebAPI.")) {
+  const paths = item.path.split(".");
+  if (paths.length === 3) {
+    link = `${import.meta.env.BASE_URL}/${createAPIModuleLink(paths[1])}#${paths[2]}`;
   }
 }
+
+const genericTypeParameters = item.genericTypeParameters || [];
 ---
 
-{link ? <a href={link}>{item.ident}</a> : item.ident}
-{
-  item.genericArguments.length > 0 && (
-    <>
-      {"<"}
-      {item.genericArguments.map((subItem) => (
-        <Astro.self typesInOwnModule={typesInOwnModule} item={subItem} />
-      ))}
-      {">"}
-    </>
-  )
-}
+<span>
+  {link ? <a href={link}>{item.path}</a> : item.path}{
+    genericTypeParameters.length > 0 && (
+      <>
+        {"<"}
+        {genericTypeParameters.map((subItem) => (
+          <Astro.self typesInOwnModule={typesInOwnModule} item={subItem} />
+        ))}
+        {">"}
+      </>
+    )
+  }
+</span>
+<style>
+  span {
+    display: inline-flex;
+    color: var(--sl-color-accent-low);
+  }
+</style>
diff --git a/docs/components/value.astro b/docs/components/value.astro
@@ -0,0 +1,27 @@
+---
+import SignatureItem from "./signatureItem.astro";
+const { parameters, returnType } = Astro.props;
+---
+
+<div class="value">
+  <h4>Parameters</h4>
+  {
+    parameters.map((p) => (
+      <SignatureItem item={p}   />
+    ))
+  }
+  <h4>Return type</h4>
+  <SignatureItem item={returnType} />
+</div>
+<style>
+  .value {
+    display: flex;
+    flex-direction: column;
+    padding-bottom: 1rem;
+    border-bottom: 1px solid var(--sl-color-gray-7);
+
+    .signature {
+      margin-top: 0rem;
+    }
+  }
+</style>
diff --git a/docs/pages/apidocs/[API].astro b/docs/pages/apidocs/[API].astro
@@ -1,5 +1,7 @@
 ---
-import { apiModules, getDoc } from "./utils";
+import * as path from "node:path";
+import { existsSync } from "fs";
+import { apiModules, getDoc, createTypeModuleLink } from "../../utils";
 import StarlightPage from "@astrojs/starlight/components/StarlightPage.astro";
 import { Code } from "@astrojs/starlight/components";
 import { micromark } from "micromark";
@@ -20,7 +22,17 @@ function showRecord(details) {
   return details && details.kind === "record" && details.items.length > 0;
 }
 
-const { moduleName, filePath } = Astro.props;
+function getModuleFileName(typeName) {
+  return `${typeName[0].toUpperCase()}${typeName.slice(1)}`;
+}
+
+function showModule(typeName, filePath) {
+  const moduleFileName = `${getModuleFileName(typeName)}.res`;
+  const potentialPath = path.join(filePath.replace(".res", ""), moduleFileName);
+  return existsSync(potentialPath);
+}
+
+const { moduleName, filePath, link } = Astro.props;
 
 const docInfo = await getDoc(filePath);
 
@@ -76,6 +88,20 @@ const headings = [
               {...type.detail}
             />
           ) : null}
+          {showModule(type.name, filePath) && (
+            <>
+              <h4>Module</h4>
+              <p>
+                There are methods and helpers defined in{" "}
+                <a
+                  href={`${import.meta.env.BASE_URL}/${createTypeModuleLink(link, type.name)}`}
+                >
+                  {getModuleFileName(type.name)}
+                </a>
+                .
+              </p>
+            </>
+          )}
         </div>
       ))
     }
diff --git a/docs/pages/apidocs/[API]/[Module].astro b/docs/pages/apidocs/[API]/[Module].astro
@@ -1,9 +1,9 @@
 ---
-import { apiModules, getDoc } from "../utils";
-// import StarlightPage from "@astrojs/starlight/components/StarlightPage.astro";
-// import { Code } from "@astrojs/starlight/components";
-// import { micromark } from "micromark";
-// import Record from "../../components/record.astro";
+import { apiModules, getDoc } from "../../../utils";
+import StarlightPage from "@astrojs/starlight/components/StarlightPage.astro";
+import { Code } from "@astrojs/starlight/components";
+import { micromark } from "micromark";
+import Value from "../../../components/value.astro";
 
 export async function getStaticPaths() {
   return apiModules.flatMap((apiModule) => {
@@ -19,7 +19,68 @@ export async function getStaticPaths() {
   });
 }
 
-const name = Astro.props.currentModule.moduleName;
+function showValue(detail) {
+  return (
+    detail?.kind === "signature" && detail?.details?.parameters?.length > 0
+  );
+}
+
+const { filePath, moduleName } = Astro.props.currentModule;
+const docInfo = await getDoc(filePath);
+
+const values = docInfo.items
+  .filter((item) => item.kind === "value")
+  .sort((a, b) => a.name.localeCompare(b.name))
+  .map((value) => {
+    const documentation =
+      value.docstrings && micromark(value.docstrings.join("\n"));
+    return {
+      name: value.name,
+      documentation,
+      signature: value.signature,
+      detail: value.detail,
+    };
+  });
+
+const valueHeadings = values.map((value) => ({
+  depth: 3,
+  slug: value.name,
+  text: value.name,
+}));
+
+const frontmatter = {
+  title: moduleName,
+};
+
+const headings = [
+  {
+    depth: 2,
+    slug: "values",
+    text: "Values",
+  },
+  ...valueHeadings,
+];
 ---
 
-<h1>Yupla {name}</h1>
+<StarlightPage frontmatter={frontmatter} headings={headings}>
+  <h2 id="values">Values</h2>
+  {
+    values.map((value) => (
+      <div class="rescript_value">
+        <h3 id={value.name}>{value.name}</h3>
+        <div set:html={value.documentation} />
+        <Code lang="ReScript" code={value.signature} />
+        {showValue(value.detail) && <Value {...value.detail.details} />}
+      </div>
+    ))
+  }
+  <pre>
+{JSON.stringify(docInfo, null, 4)}
+</pre>
+</StarlightPage>
+<style>
+  pre {
+    max-width: 100%;
+    overflow-x: auto;
+  }
+</style>
diff --git a/docs/pages/apidocs/index.astro b/docs/pages/apidocs/index.astro
@@ -1,6 +1,6 @@
 ---
 import StarlightPage from "@astrojs/starlight/components/StarlightPage.astro";
-import { apiModules } from "./utils";
+import { apiModules } from "../../utils";
 
 const frontmatter = {
   title: "API Documentation",
@@ -14,14 +14,13 @@ const headings = [
   },
 ];
 
-const resFiles = apiModules;
 ---
 
 <StarlightPage frontmatter={frontmatter} headings={headings}>
   <h2 id="web-apis">Web APIs</h2>
   <ul>
     {
-      resFiles.map(({ moduleName, link }) => (
+      apiModules.map(({ moduleName, link }) => (
         <li>
           <a href={link}>{moduleName}</a>
         </li>
diff --git a/docs/utils.js b/docs/utils.js
@@ -12,8 +12,14 @@ function toKebabCase(input) {
     .toLowerCase(); // Convert to lowercase
 }
 
-export function createModuleLink(moduleName) {
-  return `/apidocs/${toKebabCase(moduleName)}`;
+export function createAPIModuleLink(moduleName) {
+  // This function is called before import.meta.env.BASE_URL is set.
+  // So, I'm hardcoding the path here.
+  return `apidocs/${toKebabCase(moduleName)}`;
+}
+
+export function createTypeModuleLink(parentModuleLink, typeName) {
+  return `${parentModuleLink}/${toKebabCase(typeName)}`;
 }
 
 function mapTypeModules(parentModuleLink, file) {
@@ -27,20 +33,20 @@ function mapTypeModules(parentModuleLink, file) {
   return files
     .filter((f) => f.endsWith(".res"))
     .map((file) => {
-      const fullPath = path.join(folder, file);
+      const filePath = path.join(folder, file);
 
       const moduleName = file
         .replace("$", "")
         .replace(folder, "")
         .replace(".res", "");
       const apiRouteParameter = toKebabCase(moduleName);
-      const link = `${parentModuleLink}/${apiRouteParameter}`;
+      const link = createTypeModuleLink(parentModuleLink, moduleName);
       const typeName = moduleName[0].toLocaleLowerCase() + moduleName.slice(1);
 
       return [
         typeName,
         {
-          fullPath,
+          filePath,
           moduleName,
           link,
           apiRouteParameter,
@@ -49,13 +55,10 @@ function mapTypeModules(parentModuleLink, file) {
     });
 }
 
-function mapRescriptFile(file) {
-  const moduleName = path
-    .basename(file, ".res")
-    .replace("$", "")
-    .replace("API", " API");
-  const filePath = path.join(import.meta.dirname, file);
-  const link = createModuleLink(moduleName);
+function mapRescriptFile(srcDir, file) {
+  const moduleName = path.basename(file, ".res").replace("$", "");
+  const filePath = path.join(srcDir, file);
+  const link = createAPIModuleLink(moduleName);
   const items = Object.fromEntries(mapTypeModules(link, filePath));
 
   return {
@@ -67,13 +70,8 @@ function mapRescriptFile(file) {
   };
 }
 
-export const apiModules = Object.keys(
-  import.meta.glob("../../../src/*.res"),
-).map(mapRescriptFile);
-
-export const fileModules = Object.keys(
-  import.meta.glob("../../../src/**/*.res"),
-).map(mapRescriptFile);
+const srcDir = path.resolve(process.cwd(), "src");
+export const apiModules = readdirSync(srcDir).filter(f => f.endsWith(".res")).map(r => mapRescriptFile(srcDir, r));
 
 export async function getDoc(absoluteFilePath) {
   const { stdout, stderr } = await execAsync(
