refactor(reference): generate HTML files with the deno/doc jsr packag…

…e instead of CLI (denoland#1146)

.github/workflows/deploy.yml

@@ -20,12 +20,6 @@ jobs:
       - name: Set up Deno
         uses: denoland/setup-deno@v2
 
-      - name: Set up Deno
-        uses: denoland/setup-deno@v2
-        with:
-          deno-version: canary
-          deno-binary-name: "deno_doc"
-
       - name: "Reference: install"
         working-directory: "reference_gen"
         run: deno install
@@ -36,7 +30,7 @@ jobs:
 
       - name: "Reference: generate docs"
         working-directory: "reference_gen"
-        run: deno_doc task doc
+        run: deno task doc
 
       - name: Build
         env:

reference_gen/common.ts

@@ -0,0 +1,44 @@
+import { HrefResolver, ShortPath } from "@deno/doc";
+import { dirname, join } from "@std/path";
+
+export function renderMarkdown(
+  md: string,
+  titleOnly: boolean,
+  _filePath: ShortPath | undefined,
+  anchorizer: (content: string, depthLevel: number) => string,
+): string | undefined {
+  return md;
+}
+
+export function stripMarkdown(md: string): string {
+  return md;
+}
+
+export const hrefResolver: HrefResolver = {
+  resolvePath(_current, _target, defaultResolve) {
+    let path = defaultResolve();
+
+    if (path.endsWith("index.html")) {
+      path = path.slice(0, -"index.html".length);
+    } else if (path.endsWith(".html")) {
+      path = path.slice(0, -".html".length);
+    }
+
+    return path;
+  },
+};
+
+export async function writeFiles(root: string, files: Record<string, string>) {
+  await Deno.remove(root, { recursive: true });
+
+  await Promise.all(
+    Object.entries(files).map(async ([path, content]) => {
+      const joined = join(root, path);
+
+      await Deno.mkdir(dirname(joined), { recursive: true });
+      await Deno.writeTextFile(joined, content);
+    }),
+  );
+
+  console.log(`Written ${Object.keys(files).length} files`);
+}

reference_gen/deno-categories.json

@@ -13,5 +13,5 @@
   "Runtime": "System-related functionality, process management, and observability. \n\nEg {@linkcode Deno.mainModule}, {@linkcode Deno.exit}, {@linkcode Deno.cwd}",
   "Sub Process": "Spawn and manage child processes, execute commands, and collect output. Useful for executing external programs from Deno.\n\nEg {@linkcode Deno.Command}",
   "Testing": "Robust testing and benchmarking capabilities to ensure code quality and performance.\n\nEg {@linkcode Deno.test}, {@linkcode Deno.bench}",
-  "Web Sockets": "Enable real-time communication between clients and servers using WebSockets. Tools to create interactive and dynamic applications.\n\nEg {@linkcode WebSocket}"
+  "WebSockets": "Enable real-time communication between clients and servers using WebSockets. Tools to create interactive and dynamic applications.\n\nEg {@linkcode WebSocket}"
 }

reference_gen/deno-doc.ts

@@ -0,0 +1,33 @@
+import { doc, generateHtml } from "@deno/doc";
+import {
+  hrefResolver,
+  renderMarkdown,
+  stripMarkdown,
+  writeFiles,
+} from "./common.ts";
+import categoryDocs from "./deno-categories.json" with { type: "json" };
+
+const url = import.meta.resolve("./types/deno.d.ts");
+
+console.log("Generating doc nodes...");
+
+const nodes = await doc(url, { includeAll: true });
+
+console.log("Generating html files...");
+
+const files = await generateHtml({ [url]: nodes }, {
+  packageName: "Deno",
+  categoryDocs,
+  disableSearch: true,
+  hrefResolver,
+  usageComposer: {
+    singleMode: true,
+    compose(_currentResolve, _usageToMd) {
+      return new Map();
+    },
+  },
+  markdownRenderer: renderMarkdown,
+  markdownStripper: stripMarkdown,
+});
+
+await writeFiles("./gen/deno", files);

reference_gen/deno.jsonc

@@ -1,26 +1,26 @@
 {
-  "nodeModulesDir": true,
-  "lock": false, // TODO(@crowlKats): remove when 2.0 releases
+  "nodeModulesDir": "auto",
   "imports": {
     "@b-fuze/deno-dom": "jsr:@b-fuze/deno-dom@^0.1.47",
     "@std/async": "jsr:@std/async@^0.224.2",
     "@std/fs": "jsr:@std/fs@^1.0.1",
     "@std/media-types": "jsr:@std/media-types@^0.224.1",
     "@std/path": "jsr:@std/path@^0.225.1",
     "@std/yaml": "jsr:@std/yaml@^1.0.3",
+    "@deno/doc": "jsr:@deno/[email protected]",
     "@types/node": "npm:@types/[email protected]",
     "browserslist": "npm:[email protected]",
     "dax": "jsr:@david/dax@^0.40.1",
     "lightningcss": "npm:[email protected]",
     "ts-morph": "jsr:@ts-morph/[email protected]"
   },
   "tasks": {
-    "types:deno": "deno run --allow-read --allow-write --allow-run --allow-env --allow-sys deno-docs.ts",
-    "types:node": "deno run --allow-read --allow-write=. --allow-env --allow-sys node-docs.ts",
+    "types:deno": "deno run --allow-read --allow-write --allow-run --allow-env --allow-sys deno-types.ts",
+    "types:node": "deno run --allow-read --allow-write=. --allow-env --allow-sys node-types.ts",
     "types": "deno task types:deno && deno task types:node",
-    "doc:deno": "mkdir -p gen/deno && DENO_INTERNAL_HTML_DOCS=deno deno doc --html --name=Deno --category-docs=deno-categories.json --output=gen/deno --strip-trailing-html types/deno.d.ts",
-    "doc:web": "mkdir -p gen/web && DENO_INTERNAL_HTML_DOCS=deno deno doc --html --name=Web --category-docs=web-categories.json --output=gen/web --strip-trailing-html types/web.d.ts",
-    "doc:node": "mkdir -p gen/node && DENO_INTERNAL_HTML_DOCS=node deno doc --html --name=Node --output=gen/node --symbol-redirect-map=node-symbol-map.json --default-symbol-map=node-default-map.json --strip-trailing-html types/node/[!_]*",
+    "doc:deno": "mkdir -p gen/deno && deno run --allow-read --allow-write --allow-env --allow-net deno-doc.ts",
+    "doc:web": "mkdir -p gen/web && deno run --allow-read --allow-write --allow-env --allow-net web-doc.ts",
+    "doc:node": "mkdir -p gen/node && deno run --allow-read --allow-write --allow-env --allow-net node-doc.ts",
     "doc": "deno task doc:deno && deno task doc:web && deno task doc:node"
   },
   "exports": {