fixup!

Author: avivkeller

generate-md.mjs

@@ -1,30 +1,31 @@
-import { Application } from "typedoc";
-import { fileURLToPath } from "node:url";
-import { resolve, dirname } from "node:path";
+import { Application } from 'typedoc';
 
-// Get the current file's directory
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-// Define all paths relative to the current file
-const entryPointsPath = resolve(__dirname, "./webpack/types.d.ts");
-const tsconfigPath = resolve(__dirname, "./tsconfig.json");
-const dockitTheme = resolve(__dirname, "./plugins/theme/index.mjs");
-const consolidationPlugin = resolve(__dirname, "./plugins/consolidation.mjs");
-
-Application.bootstrapWithPlugins({
-  entryPoints: [entryPointsPath],
-  out: "generated-api",
+const app = await Application.bootstrapWithPlugins({
+  entryPoints: ['./webpack/types.d.ts'],
+  out: 'generated-api',
 
   // Plugins
-  plugin: ["typedoc-plugin-markdown", consolidationPlugin, dockitTheme],
+  plugin: [
+    'typedoc-plugin-markdown',
+    './plugins/processor.mjs',
+    './plugins/theme/index.mjs',
+  ],
+  theme: 'doc-kit',
+
+  // Formatting
   hideGroupHeadings: true,
   hideBreadcrumbs: true,
-  theme: "doc-kit",
-
-  tsconfig: tsconfigPath,
-  entryFileName: "index",
   hidePageHeader: true,
   disableSources: true,
+
   router: 'module',
-}).then(async (app) => app.generateOutputs(await app.convert()));
+  entryFileName: 'index',
+
+  tsconfig: 'tsconfig.json',
+});
+
+const project = await app.convert();
+
+if (project) {
+  await app.generateOutputs(project);
+}

package-lock.json

@@ -1,6 +1,6 @@
 {
   "scripts": {
-    "build": "node generate-md.mjs && doc-kit generate -t web -i generated-api/webpack/namespaces/*.md -o out"
+    "build": "node generate-md.mjs && doc-kit generate -t web -i generated-api/webpack/namespaces/*.md --type-map ./generated-type-map.json -o out"
   },
   "devDependencies": {
     "@node-core/doc-kit": "^1.0.1",

package.json

@@ -0,0 +1,33 @@
+import { Converter, ReflectionKind, Renderer } from 'typedoc';
+import { writeFileSync } from 'node:fs';
+/**
+ * @param {import('typedoc-plugin-markdown').MarkdownApplication} app
+ */
+export function load(app) {
+  // Merge `export=` namespaces into their parent
+  app.converter.on(Converter.EVENT_RESOLVE_BEGIN, (context) => {
+    context.project
+      .getReflectionsByKind(ReflectionKind.Namespace)
+      .filter((ref) => ref.name === 'export=')
+      .forEach((namespace) =>
+        context.project.mergeReflections(namespace, namespace.parent),
+      );
+  });
+
+  app.renderer.on(Renderer.EVENT_END, (context) => {
+    const typeMap = Object.fromEntries(
+      context.project
+        .getReflectionsByKind(ReflectionKind.All)
+        .filter((ref) => app.renderer.router.hasUrl(ref))
+        .map((reference) => [
+          reference.name,
+          app.renderer.router
+            .getFullUrl(reference)
+            .replace('.md', '.html')
+            .replace('webpack/namespaces/', ''),
+        ]),
+    );
+
+    writeFileSync('generated-type-map.json', JSON.stringify(typeMap, null, 2));
+  });
+}

plugins/consolidation.mjs

@@ -0,0 +1,33 @@
+/**
+ * @typedef {object} TypedListEntry
+ * @property {string} [label]
+ * @property {string} [name]
+ * @property {import("typedoc").SomeType | string} [type]
+ * @property {import("typedoc").Comment | import("typedoc").CommentTag} [comment]
+ */
+
+/**
+ * @param {import('typedoc-plugin-markdown').MarkdownThemeContext} ctx
+ * @returns {import('typedoc-plugin-markdown').MarkdownThemeContext['helpers']}
+ */
+export default (ctx) => ({
+  ...ctx.helpers,
+
+  typedListItem({ label, name, type, comment }) {
+    const namePart = label ? ` ${label}:` : name ? ` \`${name}\`` : '';
+
+    const typePart = type
+      ? ` ${typeof type === 'string' ? type : ctx.partials.someType(type)}`
+      : '';
+
+    const descPart = comment
+      ? ` ${ctx.helpers.getCommentParts(comment.summary ?? comment.content)}`
+      : '';
+
+    return `*${namePart}${typePart}${descPart}`;
+  },
+
+  typedList(entries) {
+    return entries.map(ctx.helpers.typedListItem).join('\n');
+  },
+});

plugins/processor.mjs

@@ -1,101 +1,26 @@
-import { MarkdownTheme, MarkdownThemeContext } from "typedoc-plugin-markdown";
-import { ReflectionKind } from "typedoc";
-import * as typePartials from "./types.mjs";
-
-const KIND_PREFIX = {
-  [ReflectionKind.Class]: "Class",
-  [ReflectionKind.Interface]: "Interface",
-  [ReflectionKind.Enum]: "Enum",
-  [ReflectionKind.TypeAlias]: "Type",
-  [ReflectionKind.Namespace]: "Namespace",
-  [ReflectionKind.Constructor]: "Constructor",
-  [ReflectionKind.Property]: "Property",
-  [ReflectionKind.Accessor]: "Accessor",
-};
-
-const STATIC_PREFIX = {
-  [ReflectionKind.Method]: "Static method",
-};
-
-const resolveMemberPrefix = (model) =>
-  model.flags?.isStatic ? STATIC_PREFIX[model.kind] : KIND_PREFIX[model.kind];
+import { MarkdownTheme, MarkdownThemeContext } from 'typedoc-plugin-markdown';
+import helpers from './helpers/index.mjs';
+import partials from './partials/index.mjs';
 
 export class DocKitTheme extends MarkdownTheme {
   getRenderContext(page) {
-    this.application.options.setValue("propertiesFormat", "table");
+    this.application.options.setValue('hidePageHeader', true);
+    this.application.options.setValue('hideBreadcrumbs', true);
+    this.application.options.setValue('propertiesFormat', 'table');
     return new DocKitThemeContext(this, page, this.application.options);
   }
 }
 
 export class DocKitThemeContext extends MarkdownThemeContext {
-  helpers = {
-    ...this.helpers,
-
-    /** @param {import('typedoc').ParameterReflection} */
-    typedListItem: ({ label, name, type, comment }) => {
-      const namePart = label ? ` ${label}:` : name ? ` \`${name}\`` : "";
-      const typePart = type
-        ? ` ${typeof type === "string" ? type : this.partials.someType(type)}`
-        : "";
-      const descPart = comment
-        ? ` ${this.helpers.getCommentParts(comment.summary ?? comment.content)}`
-        : "";
-
-      return `*${namePart}${typePart}${descPart}`;
-    },
-
-    typedList: (entries) => entries.map(this.helpers.typedListItem).join("\n"),
-  };
-  partials = {
-    ...this.partials,
-    ...typePartials,
-
-    // Typed Lists
-    parametersList: this.helpers.typedList,
-    propertiesTable: this.helpers.typedList,
-    signature: (model, options) => {
-      const comment = options.multipleSignatures
-        ? model.comment
-        : model.comment || model.parent?.comment;
+  helpers = helpers(this);
 
-      return [
-        model.typeParameters?.length &&
-          this.partials.typeParametersList(model.typeParameters, {
-            headingLevel: options.headingLevel,
-          }),
-        model.parameters?.length &&
-          this.partials.parametersList(model.parameters, {
-            headingLevel: options.headingLevel,
-          }),
-        this.helpers.typedListItem({
-          label: "Returns",
-          type: model.type ?? "void",
-          comment: model.comment?.getTag("@returns"),
-        }),
-        "",
-        comment &&
-          this.partials.comment(comment, {
-            headingLevel: options.headingLevel,
-          }),
-      ]
-        .filter((x) => (typeof x === "string" ? x : Boolean(x)))
-        .join("\n");
-    },
+  partials = partials(this);
 
-    // Titles
-    memberTitle: (model) => {
-      const prefix = resolveMemberPrefix(model);
-      const params = model.signatures?.[0]?.parameters ?? null;
-      const name = params
-        ? // TODO: If params optional, wrap in `[]`
-          `\`${model.name}(${params.map((p) => p.name).join(", ")})\``
-        : `\`${model.name}\``;
-      return prefix ? `${prefix}: ${name}` : name;
-    },
+  templates = {
+    ...this.templates,
   };
 }
 
-/** @param {import('typedoc').Application} app */
 export function load(app) {
-  app.renderer.defineTheme("doc-kit", DocKitTheme);
+  app.renderer.defineTheme('doc-kit', DocKitTheme);
 }