WIP: Create a router for TypeDoc

.vscode/settings.json

@@ -55,6 +55,7 @@
         "linkcode",
         "linkify",
         "linkplain",
+        "momento",
         "Msys",
         "nodoc",
         "shiki",

CHANGELOG.md

@@ -2,6 +2,12 @@
 title: Changelog
 ---
 
+## Beta
+
+-   TypeDoc will now only create references for symbols re-exported from modules.
+-   API: Introduced a `Router` which is used for URL creation. `Reflection.url`,
+    `Reflection.anchor`, and `Reflection.hasOwnDocument` have been removed.
+
 ## Unreleased
 
 ## v0.27.2 (2024-11-29)

scripts/download_plugins.cjs

@@ -39,8 +39,8 @@ async function getPlugins() {
         });
 }
 
-function getTarballUrl(package) {
-    return exec(`npm view ${package.name} dist.tarball`);
+function getTarballUrl(pack) {
+    return exec(`npm view ${pack.name} dist.tarball`);
 }
 
 function downloadTarball(url, outDir) {

src/index.ts

@@ -51,13 +51,17 @@ export {
     RendererEvent,
     MarkdownEvent,
     IndexEvent,
+    DefaultRouter,
+    PageKind,
 } from "./lib/output/index.js";
 export type {
     RenderTemplate,
     RendererHooks,
     NavigationElement,
     RendererEvents,
     PageHeading,
+    Router,
+    PageDefinition,
 } from "./lib/output/index.js";
 
 export { Outputs } from "./lib/output/output.js";

src/lib/converter/symbols.ts

@@ -906,7 +906,13 @@ function convertAlias(
     const reflection = context.project.getReflectionFromSymbol(
         context.resolveAliasedSymbol(symbol),
     );
-    if (!reflection) {
+    if (
+        !reflection ||
+        (reflection &&
+            !reflection.parent?.kindOf(
+                ReflectionKind.Project | ReflectionKind.SomeModule,
+            ))
+    ) {
         // We don't have this, convert it.
         convertSymbol(
             context,

src/lib/models/ReflectionCategory.ts

@@ -42,13 +42,6 @@ export class ReflectionCategory {
         this.title = title;
     }
 
-    /**
-     * Do all children of this category have a separate document?
-     */
-    allChildrenHaveOwnDocument(): boolean {
-        return this.children.every((child) => child.hasOwnDocument);
-    }
-
     toObject(serializer: Serializer): JSONOutput.ReflectionCategory {
         return {
             title: this.title,

src/lib/models/ReflectionGroup.ts

@@ -53,13 +53,6 @@ export class ReflectionGroup {
         this.title = title;
     }
 
-    /**
-     * Do all children of this group have a separate document?
-     */
-    allChildrenHaveOwnDocument(): boolean {
-        return this.children.every((child) => child.hasOwnDocument);
-    }
-
     toObject(serializer: Serializer): JSONOutput.ReflectionGroup {
         return {
             title: this.title,

src/lib/models/reflections/abstract.ts

@@ -18,6 +18,8 @@ import type {
 } from "../../internationalization/index.js";
 import type { ParameterReflection } from "./parameter.js";
 import type { ReferenceReflection } from "./reference.js";
+import type { SignatureReflection } from "./signature.js";
+import type { TypeParameterReflection } from "./type-parameter.js";
 
 /**
  * Current reflection id.
@@ -294,26 +296,6 @@ export abstract class Reflection {
      */
     comment?: Comment;
 
-    /**
-     * The url of this reflection in the generated documentation.
-     * TODO: Reflections shouldn't know urls exist. Move this to a serializer.
-     */
-    url?: string;
-
-    /**
-     * The name of the anchor of this child.
-     * TODO: Reflections shouldn't know anchors exist. Move this to a serializer.
-     */
-    anchor?: string;
-
-    /**
-     * Is the url pointing to an individual document?
-     *
-     * When FALSE, the url points to an anchor tag on a page of a different reflection.
-     * TODO: Reflections shouldn't know how they are rendered. Move this to the correct serializer.
-     */
-    hasOwnDocument?: boolean;
-
     constructor(name: string, kind: ReflectionKind, parent?: Reflection) {
         this.id = REFLECTION_ID++ as ReflectionId;
         this.parent = parent;
@@ -434,6 +416,12 @@ export abstract class Reflection {
     isDeclaration(): this is DeclarationReflection {
         return false;
     }
+    isSignature(): this is SignatureReflection {
+        return false;
+    }
+    isTypeParameter(): this is TypeParameterReflection {
+        return false;
+    }
     isParameter(): this is ParameterReflection {
         return false;
     }

src/lib/models/reflections/declaration.ts

@@ -40,7 +40,7 @@ export interface DeclarationHierarchy {
  * A reflection that represents a single declaration emitted by the TypeScript compiler.
  *
  * All parts of a project are represented by DeclarationReflection instances. The actual
- * kind of a reflection is stored in its ´kind´ member.
+ * kind of a reflection is stored in its `kind` member.
  * @category Reflections
  */
 export class DeclarationReflection extends ContainerReflection {

src/lib/models/reflections/signature.ts

@@ -97,6 +97,10 @@ export class SignatureReflection extends Reflection {
         }
     }
 
+    override isSignature(): this is SignatureReflection {
+        return true;
+    }
+
     /**
      * Return a string representation of this reflection.
      */

src/lib/models/reflections/type-parameter.ts

@@ -44,6 +44,10 @@ export class TypeParameterReflection extends Reflection {
         this.varianceModifier = varianceModifier;
     }
 
+    override isTypeParameter(): this is TypeParameterReflection {
+        return true;
+    }
+
     override toObject(
         serializer: Serializer,
     ): JSONOutput.TypeParameterReflection {

src/lib/output/events.ts

@@ -1,13 +1,10 @@
-import * as Path from "path";
-
 import type { ProjectReflection } from "../models/reflections/project.js";
-import type { RenderTemplate, UrlMapping } from "./models/UrlMapping.js";
 import type {
     DeclarationReflection,
     DocumentReflection,
-    Reflection,
     ReflectionKind,
 } from "../models/index.js";
+import type { PageDefinition, PageKind } from "./router.js";
 
 /**
  * An event emitted by the {@link Renderer} class at the very beginning and
@@ -28,11 +25,9 @@ export class RendererEvent {
     readonly outputDirectory: string;
 
     /**
-     * A list of all pages that should be generated.
-     *
-     * This list can be altered during the {@link Renderer.EVENT_BEGIN} event.
+     * A list of all pages that will be generated.
      */
-    urls?: UrlMapping<Reflection>[];
+    pages: PageDefinition[];
 
     /**
      * Triggered before the renderer starts rendering a project.
@@ -46,26 +41,14 @@ export class RendererEvent {
      */
     static readonly END = "endRender";
 
-    constructor(outputDirectory: string, project: ProjectReflection) {
+    constructor(
+        outputDirectory: string,
+        project: ProjectReflection,
+        pages: PageDefinition[],
+    ) {
         this.outputDirectory = outputDirectory;
         this.project = project;
-    }
-
-    /**
-     * Create an {@link PageEvent} event based on this event and the given url mapping.
-     *
-     * @internal
-     * @param mapping  The mapping that defines the generated {@link PageEvent} state.
-     * @returns A newly created {@link PageEvent} instance.
-     */
-    public createPageEvent<Model>(
-        mapping: UrlMapping<Model>,
-    ): [RenderTemplate<PageEvent<Model>>, PageEvent<Model>] {
-        const event = new PageEvent<Model>(mapping.model);
-        event.project = this.project;
-        event.url = mapping.url;
-        event.filename = Path.join(this.outputDirectory, mapping.url);
-        return [mapping.template, event];
+        this.pages = pages;
     }
 }
 
@@ -100,6 +83,11 @@ export class PageEvent<out Model = unknown> {
      */
     url!: string;
 
+    /**
+     * The type of page this is.
+     */
+    pageKind!: PageKind;
+
     /**
      * The model that should be rendered on this page.
      */