denoland · crowlKats · Jun 20, 2024 · Jun 20, 2024 · Jun 20, 2024 · Jun 21, 2024
diff --git a/.gitignore b/.gitignore
@@ -4,6 +4,12 @@
 # Production
 /build
 
+# Reference docs
+/reference/api
+/reference/gen
+/reference/types
+/reference/node_modules
+
 # Generated files
 .docusaurus
 .cache-loader

diff --git a/deno.lock b/deno.lock
diff --git a/docusaurus.config.js b/docusaurus.config.js
@@ -1,3 +1,5 @@
+import { deploy } from "./sidebars/deploy.js";
+
 const process = require("node:process");
 const NodePolyfillPlugin = require("node-polyfill-webpack-plugin");
 const findReplace = require("./src/remark/find_replace");
@@ -10,7 +12,7 @@ const config = {
   favicon: "img/favicon.ico",
   url: "https://docs.deno.com",
   baseUrl: "/",
-  onBrokenLinks: "throw",
+  onBrokenLinks: "warn",
   onBrokenMarkdownLinks: "warn",
   i18n: {
     defaultLocale: "en",
@@ -62,6 +64,7 @@ const config = {
             cloud: {
               indexId: process.env.ORAMA_CLOUD_INDEX_ID,
               oramaCloudAPIKey: process.env.ORAMA_CLOUD_API_KEY,
+              deploy: true,
             },
           }
           : {}),
@@ -160,14 +163,15 @@ const config = {
           activeBaseRegex: `^/examples`,
         },
         {
-          href: "https://deno.land/api?unstable=true",
+          href: "pathname:///api",
           label: "API Reference",
           position: "left",
         },
         {
           href: "https://www.deno.com",
           label: "deno.com",
           position: "right",
+          activeBaseRegex: `^/api`,
         },
       ],
     },

diff --git a/package.json b/package.json
@@ -5,7 +5,7 @@
   "scripts": {
     "docusaurus": "docusaurus",
     "start": "docusaurus start",
-    "build": "docusaurus build && cp -r src-deno/* build",
+    "build": "docusaurus build && cp -r src-deno/* build && cd reference/ && deno task build && cp -r api docusaurus.css ../build",
     "swizzle": "docusaurus swizzle",
     "deploy": "docusaurus deploy",
     "clear": "docusaurus clear",

diff --git a/reference/build.ts b/reference/build.ts
@@ -0,0 +1,131 @@
+import { walk } from "@std/fs/walk";
+import { dirname, extname } from "@std/path";
+import { pooledMap } from "@std/async/pool";
+import { DOMParser } from "@b-fuze/deno-dom";
+
+const nav = await Deno.readTextFile("nav.html");
+const navDeno = await Deno.readTextFile("nav_deno.html");
+const navWeb = await Deno.readTextFile("nav_web.html");
+const navNode = await Deno.readTextFile("nav_node.html");
+
+let navHead = `
+<link rel="stylesheet" href="/docusaurus.css">
+<link data-rh="true" rel="preload" href="/fonts/inter/Inter-Italic.woff2" as="font" type="font/woff2" crossorigin="true">
+<link data-rh="true" rel="preload" href="/fonts/inter/Inter-Regular.woff2" as="font" type="font/woff2" crossorigin="true">
+<link data-rh="true" rel="preload" href="/fonts/inter/Inter-SemiBold.woff2" as="font" type="font/woff2" crossorigin="true">
+<link data-rh="true" rel="preload" href="/fonts/inter/Inter-SemiBoldItalic.woff2" as="font" type="font/woff2" crossorigin="true">
+<link data-rh="true" rel="stylesheet" href="/fonts/inter.css">`;
+
+for await (
+  const entry of walk("../build/assets/js", {
+    includeDirs: false,
+    exts: ["js"],
+  })
+) {
+  if (entry.name.includes("main")) {
+    navHead = `<script src="/assets/js/${entry.name}" defer="defer"></script>` +
+      navHead;
+  }
+}
+
+const res = pooledMap(
+  1000,
+  walk("gen", {
+    includeDirs: false,
+  }),
+  async (entry) => {
+    const outPath = `./api${entry.path.slice(3)}`;
+    await Deno.mkdir(dirname(outPath), { recursive: true });
+
+    if (extname(entry.path) === ".html") {
+      const file = await Deno.readTextFile(entry.path);
+      const document = new DOMParser().parseFromString(file, "text/html");
+
+      let subNav = "";
+      if (entry.path.startsWith("gen/deno")) {
+        subNav = navDeno;
+      } else if (entry.path.startsWith("gen/web")) {
+        subNav = navWeb;
+      } else if (entry.path.startsWith("gen/node")) {
+        subNav = navNode;
+      }
+
+      document.head.innerHTML = document.head.innerHTML + navHead;
+      document.body.innerHTML = nav + subNav + document.body.innerHTML;
+
+      await Deno.writeTextFile(
+        outPath,
+        "<!DOCTYPE html>" + document.documentElement!.outerHTML,
+        {
+          create: true,
+        },
+      );
+    } else {
+      await Deno.copyFile(entry.path, outPath);
+    }
+  },
+);
+
+await Array.fromAsync(res);
+
+const API_KEY = Deno.env.get("ORAMA_CLOUD_API_KEY");
+const INDEX_ID = Deno.env.get("ORAMA_CLOUD_INDEX_ID");
+for (const kind of ["deno", "web", "node"]) {
+  (globalThis as any).window = globalThis;
+  await import(`./gen/${kind}/search_index.js`);
+  const index = (globalThis as any as {
+    DENO_DOC_SEARCH_INDEX: {
+      nodes: {
+        name: string;
+        url: string;
+        doc: string;
+        category: string;
+        file: string;
+      }[];
+    };
+  }).DENO_DOC_SEARCH_INDEX;
+  delete (globalThis as any).window;
+
+  const searchEntries = index.nodes.map((node) => ({
+    path: new URL(node.url, `https://docs.deno.com/api/${kind}/`).pathname
+      .replace(/\.html$/, ""),
+    title: node.name,
+    content: node.doc,
+    section: `API > ${kind}${node.file !== "." ? ` > ${node.file}` : ""}${
+      node.category ? ` > ${node.category}` : ""
+    }`,
+    version: "current",
+    category: "reference",
+  }));
+
+  if (API_KEY && INDEX_ID) {
+    const res = await fetch(
+      `https://api.oramasearch.com/api/v1/webhooks/${INDEX_ID}/notify`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${Deno.env.get("ORAMA_CLOUD_API_KEY")}`,
+        },
+        body: JSON.stringify({ upsert: searchEntries }),
+      },
+    );
+    if (!res.ok) {
+      console.error("Orama update failed", res.status, await res.text());
+    }
+  }
+}
+
+const resp = await fetch(
+  `https://api.oramasearch.com/api/v1/webhooks/${INDEX_ID}/deploy`,
+  {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${API_KEY}`,
+    },
+  },
+);
+if (!resp.ok) {
+  console.error("Orama deploy failed", resp.status, await resp.text());
+}
diff --git a/reference/deno-categories.json b/reference/deno-categories.json
@@ -0,0 +1,17 @@
+{
+  "Cloud": "Tools for managing state, scheduling tasks, and interacting with key-value stores.",
+  "Errors": "Error types and utilities for handling exceptions and custom error scenarios. Helps improve error handling and debugging.",
+  "FFI": "Foreign Function Interface. Call functions from shared libraries (e.g., C/C++) directly from Deno.\n\nUseful for integrating with existing native code or accessing low-level system functionality.",
+  "Fetch": "",
+  "File System": "File System APIs for working with files, directories, and file metadata. Includes functions for reading, writing, and manipulating file paths.",
+  "GPU": "",
+  "HTTP Server": "Handling HTTP requests, serving responses, and managing server behavior.",
+  "I/O": "Interfaces for reading, writing, seeking, and managing resources. For handling of data streams, file I/O, and console interactions.",
+  "Jupyter": "Create interactive notebooks and execute code cells. Useful for data analysis, visualization, and educational purposes.",
+  "Network": "A wide range of networking tasks, from low-level connections to high-level server creation. Handle HTTP requests, WebSocket communication, and DNS resolution. Useful for building web servers, clients, and networking tools.",
+  "Permissions": "Permission system controls access to resources (e.g., file system, network, environment variables).\n\nRequest permissions explicitly, enhancing security and user trust.",
+  "Runtime": "System-related functionality, process management, and observability.",
+  "Sub Process": "Spawn and manage child processes, execute commands, and collect output. Useful for executing external programs from Deno.",
+  "Testing": "Robust testing and benchmarking capabilities to ensure code quality and performance.",
+  "Web Sockets": ""
+}
diff --git a/reference/deno-docs.ts b/reference/deno-docs.ts
@@ -0,0 +1,53 @@
+import { Project, ts } from "ts-morph";
+import $ from "dax";
+
+await Deno.mkdir("types", { recursive: true });
+
+const tempFile = await Deno.makeTempFile();
+
+await $`deno types`.stdout($.path(tempFile));
+
+const project = new Project();
+const file = project.addSourceFileAtPath(tempFile);
+
+const modules: Record<string, string> = {
+  "deno": "",
+};
+
+
+const UNSTABLE_PREFIX = "**UNSTABLE**: New API, yet to be vetted.";
+
+for (const jsdoc of file.getDescendantsOfKind(ts.SyntaxKind.JSDoc)) {
+  if (jsdoc.compilerNode.comment?.startsWith?.(UNSTABLE_PREFIX)) {
+    let jsdocBody = jsdoc.compilerNode.comment.trim()
+      .slice(UNSTABLE_PREFIX.length)
+      .trim();
+    jsdoc.setDescription(jsdocBody);
+  }
+}
+
+
+for (
+  const denoNs of file.getDescendantsOfKind(ts.SyntaxKind.ModuleDeclaration)
+    .filter((descendant) => descendant.getName() === "Deno")
+) {
+  const denoNsJSDoc = denoNs.getFirstChildIfKind(ts.SyntaxKind.JSDoc);
+  if (denoNsJSDoc) {
+    denoNsJSDoc.addTag({
+      tagName: "module",
+    });
+    modules["deno"] = denoNsJSDoc.getText() + "\n\n  " + modules["deno"];
+    denoNsJSDoc.remove();
+  }
+
+  modules["deno"] += denoNs.getFullText();
+  denoNs.remove();
+}
+
+modules["web"] = file.getFullText();
+
+await Promise.all(
+  Object.entries(modules).map(([name, content]) =>
+    Deno.writeTextFile(`types/${name}.d.ts`, content)
+  ),
+);