Skip to content

Build your personal knowledge base with Trilium Notes

feat(docs): generate User Guide pages from TypeScript declarations

Elian Doran03f65bb73630
diff --git a/apps/edit-docs/package.json b/apps/edit-docs/package.json
index 6f977bbe42..538fa1a1cb 100644
--- a/apps/edit-docs/package.json
+++ b/apps/edit-docs/package.json
@@ -12,7 +12,8 @@
"@triliumnext/core": "workspace:*",
"@triliumnext/commons": "workspace:*",
"@triliumnext/desktop": "workspace:*",
- "electron": "44.9.0"
+ "electron": "44.9.0",
+ "typedoc": "0.28.20"
},
"scripts": {
"build": "tsx scripts/build.ts",
diff --git a/apps/edit-docs/src/docs_pipeline.ts b/apps/edit-docs/src/docs_pipeline.ts
index b165566f27..71ec349612 100644
--- a/apps/edit-docs/src/docs_pipeline.ts
+++ b/apps/edit-docs/src/docs_pipeline.ts
@@ -19,6 +19,7 @@ import { deferred } from "../../../packages/commons/src/index.js";
import { buildHelpBundle } from "./help_bundle_generator.js";
import { buildHelpMeta, serializeHelpMeta, stripAppVersion } from "./help_meta_generator.js";
import { openApiToMarkdown, type OpenApiSpec } from "./openapi_markdown.js";
+import { runTypeDoc, typeDocToMarkdown } from "./typedoc_markdown.js";
export interface NoteMapping {
rootNoteId: string;
@@ -35,6 +36,8 @@ export interface NoteMapping {
helpContent?: string;
/** Pages whose Markdown is generated from an OpenAPI document before every import. */
openApiPages?: OpenApiPage[];
+ /** Pages whose Markdown is generated from TypeScript declarations before every import. */
+ typeDocPages?: TypeDocPage[];
}
export interface OpenApiPage {
@@ -44,6 +47,17 @@ export interface OpenApiPage {
spec: string;
}
+export interface TypeDocPage {
+ /** A text note of this mapping with a Markdown data file. */
+ noteId: string;
+ /** The module whose exports the page documents. Relative to the configuration file. */
+ entryPoint: string;
+ /** The tsconfig that compiles it. Relative to the configuration file. */
+ tsconfig: string;
+ /** The export the page starts with, followed by what it refers to. */
+ root?: string;
+}
+
export interface Config {
baseUrl: string;
noteMappings: NoteMapping[];
@@ -72,7 +86,12 @@ export async function loadConfig(configPath?: string): Promise<Config> {
path: path.resolve(configDir, mapping.path),
helpMeta: mapping.helpMeta ? path.resolve(configDir, mapping.helpMeta) : undefined,
helpContent: mapping.helpContent ? path.resolve(configDir, mapping.helpContent) : undefined,
- openApiPages: mapping.openApiPages?.map((page) => ({ ...page, spec: path.resolve(configDir, page.spec) }))
+ openApiPages: mapping.openApiPages?.map((page) => ({ ...page, spec: path.resolve(configDir, page.spec) })),
+ typeDocPages: mapping.typeDocPages?.map((page) => ({
+ ...page,
+ entryPoint: path.resolve(configDir, page.entryPoint),
+ tsconfig: path.resolve(configDir, page.tsconfig)
+ }))
}))
};
}
@@ -149,7 +168,7 @@ export async function importData(path: string) {
export async function importMappings(mappings: NoteMapping[]) {
for (const mapping of mappings) {
if (!mapping.exportOnly) {
- await writeOpenApiPages(mapping);
+ await writeGeneratedPages(mapping);
await importData(mapping.path);
}
}
@@ -162,21 +181,30 @@ export async function exportMappings(mappings: NoteMapping[], baseUrl: string) {
}
}
-/** Regenerates the Markdown of the mapping's `openApiPages` from their OpenAPI documents. */
-async function writeOpenApiPages(mapping: NoteMapping) {
- if (!mapping.openApiPages?.length) {
+/** Regenerates the Markdown of the mapping's `openApiPages` and `typeDocPages` from their sources. */
+async function writeGeneratedPages(mapping: NoteMapping) {
+ const pages = [
+ ...(mapping.openApiPages ?? []).map((page) => ({
+ noteId: page.noteId,
+ render: async () => openApiToMarkdown(load(await fs.readFile(page.spec, "utf-8")) as OpenApiSpec)
+ })),
+ ...(mapping.typeDocPages ?? []).map((page) => ({
+ noteId: page.noteId,
+ render: async () => typeDocToMarkdown(await runTypeDoc(page.entryPoint, page.tsconfig), page.root)
+ }))
+ ];
+ if (!pages.length) {
return;
}
const meta = JSON.parse(await fs.readFile(path.join(mapping.path, "!!!meta.json"), "utf-8")) as NoteMetaFile;
- for (const page of mapping.openApiPages) {
+ for (const page of pages) {
const dataFile = findDataFile(meta.files, page.noteId);
if (!dataFile?.endsWith(".md")) {
- throw new Error(`OpenAPI page ${page.noteId} needs a Markdown data file in ${mapping.path}.`);
+ throw new Error(`Generated page ${page.noteId} needs a Markdown data file in ${mapping.path}.`);
}
- const spec = load(await fs.readFile(page.spec, "utf-8")) as OpenApiSpec;
- await fs.writeFile(path.join(mapping.path, dataFile), openApiToMarkdown(spec));
+ await fs.writeFile(path.join(mapping.path, dataFile), await page.render());
}
}
diff --git a/apps/edit-docs/src/typedoc_markdown.spec.ts b/apps/edit-docs/src/typedoc_markdown.spec.ts
new file mode 100644
index 0000000000..06970badf8
--- /dev/null
+++ b/apps/edit-docs/src/typedoc_markdown.spec.ts
@@ -0,0 +1,146 @@
+import { mkdtemp, rm, writeFile } from "fs/promises";
+import { tmpdir } from "os";
+import { join } from "path";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+
+import { runTypeDoc, typeDocToMarkdown } from "./typedoc_markdown.js";
+
+const FIXTURE = `
+/**
+ * The demo API, exposed as \`window.demoApi\`.
+ *
+ * @packageDocumentation
+ */
+
+/** Options of {@link DemoWindowApi.resize}. */
+export interface ResizeOptions {
+ /** The new width. */
+ width: Size;
+ animate?: boolean;
+}
+
+/** A size in pixels. */
+export type Size = number | "auto";
+
+/** An export the root never reaches. */
+export interface Unreached {
+ flag: boolean;
+}
+
+/** Window controls. */
+export interface DemoWindowApi {
+ /**
+ * Resizes the window.
+ *
+ * @param options How to resize.
+ * @returns Whether it resized.
+ */
+ resize(options: ResizeOptions): Promise<boolean>;
+
+ /** Calls back when the window closes. */
+ onClose(callback: (reason: string) => void): () => void;
+
+ /** @deprecated Use {@link resize}. */
+ maximize(): void;
+}
+
+/** The root of the API. */
+export interface DemoApi {
+ /** Window controls. */
+ window: DemoWindowApi;
+ /** The version, as in \`1.2.3\`. */
+ readonly version: string;
+}
+`;
+
+describe("typeDocToMarkdown", () => {
+ let dir: string;
+ let markdown: string;
+
+ beforeAll(async () => {
+ dir = await mkdtemp(join(tmpdir(), "typedoc-markdown-"));
+ await writeFile(join(dir, "api.ts"), FIXTURE);
+ await writeFile(join(dir, "tsconfig.json"), JSON.stringify({
+ compilerOptions: { strict: true, target: "ES2022", module: "ESNext", moduleResolution: "bundler" },
+ files: [ "api.ts" ]
+ }));
+ markdown = typeDocToMarkdown(await runTypeDoc(join(dir, "api.ts"), join(dir, "tsconfig.json")), "DemoApi");
+ }, 60_000);
+
+ afterAll(async () => {
+ await rm(dir, { recursive: true, force: true });
+ });
+
+ it("opens with the package comment, then the root and what it reaches, in order of reference", () => {
+ expect(markdown.startsWith("The demo API, exposed as `window.demoApi`.\n\n## `DemoApi`")).toBe(true);
+
+ const order = [ ...markdown.matchAll(/^## `(\w+)`/gm) ].map(([ , name ]) => name);
+ // Exports the root never reaches follow, in source order.
+ expect(order).toEqual([ "DemoApi", "DemoWindowApi", "ResizeOptions", "Size", "Unreached" ]);
+ });
+
+ it("lists properties in a table, their type above their description", () => {
+ expect(markdown).toContain([
+ "## `DemoApi`",
+ "",
+ "The root of the API.",
+ "",
+ "| Property | Description |",
+ "| --- | --- |",
+ "| `window` | `DemoWindowApi`<br>Window controls. |",
+ "| `version` | `string`<br>The version, as in `1.2.3`. |"
+ ].join("\n"));
+ // An optional property says so under its name; a union's pipe is escaped in its cell.
+ expect(markdown).toContain("| `width` | `Size`<br>The new width. |");
+ expect(markdown).toContain("| `animate`<br>*optional* | `boolean` |");
+ });
+
+ it("gives each method its signature, parameters and return value", () => {
+ expect(markdown).toContain([
+ "### `resize`",
+ "",
+ "```ts",
+ "resize(options: ResizeOptions): Promise<boolean>",
+ "```",
+ "",
+ "Resizes the window.",
+ "",
+ "| Parameter | Description |",
+ "| --- | --- |",
+ "| `options` | `ResizeOptions`<br>How to resize. |",
+ "",
+ "**Returns** `Promise<boolean>`: Whether it resized."
+ ].join("\n"));
+ // A function type is written out; a method without a documented return still names its type.
+ expect(markdown).toContain("onClose(callback: (reason: string) => void): () => void");
+ expect(markdown).toContain("| `callback` | `(reason: string) => void` |");
+ expect(markdown).toContain("**Returns** `() => void`");
+ });
+
+ it("warns about a deprecated member and writes links as code", () => {
+ expect(markdown).toContain([
+ "### `maximize`",
+ "",
+ "```ts",
+ "maximize(): void",
+ "```",
+ "",
+ "> [!WARNING]",
+ "> Deprecated. Use `resize`."
+ ].join("\n"));
+ expect(markdown).not.toContain("**Returns** `void`");
+ expect(markdown).toContain("Options of `DemoWindowApi.resize`.");
+ });
+
+ it("writes a type alias as its declaration", () => {
+ expect(markdown).toContain([
+ "## `Size`",
+ "",
+ "A size in pixels.",
+ "",
+ "```ts",
+ "type Size = number | \"auto\"",
+ "```"
+ ].join("\n"));
+ });
+});
diff --git a/apps/edit-docs/src/typedoc_markdown.ts b/apps/edit-docs/src/typedoc_markdown.ts
new file mode 100644
index 0000000000..19eb7aa5f0
--- /dev/null
+++ b/apps/edit-docs/src/typedoc_markdown.ts
@@ -0,0 +1,295 @@
+/**
+ * Renders the declarations of a TypeScript module, as TypeDoc reads them, as the Markdown body of
+ * a User Guide page. The page's title comes from its note, so the output starts with the module's
+ * `@packageDocumentation` comment rather than an H1.
+ */
+import type { JSONOutput } from "typedoc";
+
+type Project = JSONOutput.ProjectReflection;
+type Declaration = JSONOutput.DeclarationReflection;
+type Signature = JSONOutput.SignatureReflection;
+type SomeType = JSONOutput.SomeType;
+type Comment = JSONOutput.Comment;
+
+/** Runs TypeDoc on one entry point and returns its model, as `typedoc --json` writes it. */
+export async function runTypeDoc(entryPoint: string, tsconfig: string): Promise<Project> {
+ const { Application, normalizePath } = await import("typedoc");
+ const app = await Application.bootstrap({
+ // Entry points are globs, which take `/` as the only separator.
+ entryPoints: [ entryPoint.replaceAll("\\", "/") ],
+ tsconfig,
+ skipErrorChecking: true,
+ sort: [ "source-order" ],
+ excludePrivate: true,
+ logLevel: "Error"
+ });
+ const project = await app.convert();
+ if (!project || app.logger.hasErrors()) {
+ throw new Error(`TypeDoc could not convert ${entryPoint}.`);
+ }
+
+ return app.serializer.projectToObject(project, normalizePath(process.cwd()));
+}
+
+/**
+ * Renders `root` first, then the declarations it reaches in order of first reference, then the
+ * remaining exports in source order. Without `root`, the exports follow in source order.
+ */
+export function typeDocToMarkdown(project: Project, root?: string): string {
+ const blocks: string[] = [];
+ if (project.comment) {
+ blocks.push(renderComment(project.comment));
+ }
+
+ for (const declaration of orderDeclarations(project.children ?? [], root)) {
+ blocks.push(...renderDeclaration(declaration));
+ }
+
+ return blocks.filter(Boolean).join("\n\n");
+}
+
+/** The `ReflectionKind` values this module renders. */
+const KIND = {
+ interface: 256,
+ typeAlias: 2097152,
+ property: 1024,
+ method: 2048,
+ accessor: 262144
+};
+
+function orderDeclarations(declarations: Declaration[], root: string | undefined) {
+ const byName = new Map(declarations.map((declaration) => [ declaration.name, declaration ]));
+ const ordered = new Set<Declaration>();
+ const queue = root && byName.has(root) ? [ root ] : [];
+
+ while (queue.length) {
+ const declaration = byName.get(queue.shift() ?? "");
+ if (!declaration || ordered.has(declaration)) {
+ continue;
+ }
+
+ ordered.add(declaration);
+ queue.push(...referencedNames(declaration).filter((name) => byName.has(name)));
+ }
+
+ for (const declaration of declarations) {
+ ordered.add(declaration);
+ }
+
+ return [ ...ordered ];
+}
+
+/** The names of the types a declaration refers to, in the order they appear in it. */
+function referencedNames(declaration: Declaration) {
+ const names: string[] = [];
+ const visit = (value: unknown) => {
+ if (Array.isArray(value)) {
+ for (const item of value) {
+ visit(item);
+ }
+ } else if (value && typeof value === "object") {
+ const node = value as Record<string, unknown>;
+ if (node.type === "reference" && typeof node.name === "string") {
+ names.push(node.name);
+ }
+ for (const [ key, child ] of Object.entries(node)) {
+ if (key !== "comment") {
+ visit(child);
+ }
+ }
+ }
+ };
+ visit(declaration);
+ return names;
+}
+
+function renderDeclaration(declaration: Declaration) {
+ const blocks = [ `## ${code(declaration.name)}` ];
+ if (declaration.comment) {
+ blocks.push(renderComment(declaration.comment));
+ }
+
+ if (declaration.kind === KIND.typeAlias) {
+ blocks.push(fence(`type ${declaration.name} = ${typeToString(declaration.type)}`));
+ return blocks;
+ }
+
+ const members = declaration.children ?? [];
+ const properties = members.filter((member) => member.kind === KIND.property || member.kind === KIND.accessor);
+ const methods = members.filter((member) => member.kind === KIND.method);
+
+ if (properties.length) {
+ blocks.push(table([ "Property", "Description" ], properties.map((property) => [
+ property.flags.isOptional ? `${code(property.name)}<br>*optional*` : code(property.name),
+ details(typeToString(property.type ?? property.getSignature?.type), property.comment)
+ ])));
+ }
+
+ for (const method of methods) {
+ blocks.push(...renderMethod(method));
+ }
+
+ return blocks;
+}
+
+function renderMethod(method: Declaration) {
+ const signatures = method.signatures ?? [];
+ const blocks = [ `### ${code(method.name)}`, fence(signatures.map(signatureToString).join("\n")) ];
+
+ // Overloads share one entry, described by the first signature that has a comment.
+ const signature = signatures.find((candidate) => candidate.comment) ?? signatures[0];
+ if (!signature) {
+ return blocks;
+ }
+
+ if (signature.comment) {
+ blocks.push(renderComment(signature.comment));
+ }
+
+ const parameters = signature.parameters ?? [];
+ if (parameters.length) {
+ blocks.push(table([ "Parameter", "Description" ], parameters.map((parameter) => [
+ parameter.flags.isOptional ? `${code(parameter.name)}<br>*optional*` : code(parameter.name),
+ details(typeToString(parameter.type), parameter.comment)
+ ])));
+ }
+
+ const returnType = typeToString(signature.type);
+ if (returnType !== "void") {
+ const description = blockTag(signature.comment, "@returns");
+ blocks.push(`**Returns** ${code(returnType)}${description ? `: ${description}` : ""}`);
+ }
+
+ return blocks;
+}
+
+/** A comment's summary, followed by a warning when it carries `@deprecated`. */
+function renderComment(comment: Comment) {
+ const blocks = [ partsToMarkdown(comment.summary) ];
+ const deprecated = comment.blockTags?.find((tag) => tag.tag === "@deprecated");
+ if (deprecated) {
+ const reason = partsToMarkdown(deprecated.content);
+ blocks.push(`> [!WARNING]\n> Deprecated.${reason ? ` ${reason.replace(/\n/g, "\n> ")}` : ""}`);
+ }
+
+ return blocks.filter(Boolean).join("\n\n");
+}
+
+function blockTag(comment: Comment | undefined, tag: string) {
+ const content = comment?.blockTags?.find((candidate) => candidate.tag === tag)?.content;
+ return content ? partsToMarkdown(content) : "";
+}
+
+/** Comment text as Markdown; a `{@link}` becomes its target's name as code. */
+function partsToMarkdown(parts: JSONOutput.CommentDisplayPart[]) {
+ return parts.map((part) => part.kind === "inline-tag" ? code(part.text) : part.text).join("").trim();
+}
+
+/** A table cell holding a type, with the description on the line below. */
+function details(type: string, comment: Comment | undefined) {
+ const description = comment ? partsToMarkdown(comment.summary).replace(/\s*\n\s*/g, " ") : "";
+ return [ code(type), description ].filter(Boolean).join("<br>");
+}
+
+function signatureToString(signature: Signature) {
+ return `${signature.name}${parametersToString(signature)}: ${typeToString(signature.type)}`;
+}
+
+function parametersToString(signature: Signature) {
+ const parameters = (signature.parameters ?? []).map((parameter) => {
+ const rest = parameter.flags.isRest ? "..." : "";
+ const optional = parameter.flags.isOptional ? "?" : "";
+ return `${rest}${parameter.name}${optional}: ${typeToString(parameter.type)}`;
+ });
+ return `(${parameters.join(", ")})`;
+}
+
+/** A type as TypeScript writes it. */
+function typeToString(type: SomeType | undefined): string {
+ if (!type) {
+ return "";
+ }
+
+ switch (type.type) {
+ case "intrinsic":
+ return type.name;
+ case "reference": {
+ const args = type.typeArguments?.map(typeToString).join(", ");
+ return args ? `${type.name}<${args}>` : type.name;
+ }
+ case "literal":
+ return type.value === null ? "null"
+ : typeof type.value === "object" ? `${type.value.negative ? "-" : ""}${type.value.value}n`
+ : JSON.stringify(type.value);
+ case "array":
+ return `${wrap(type.elementType)}[]`;
+ case "union":
+ return type.types.map(typeToString).join(" | ");
+ case "intersection":
+ return type.types.map(wrap).join(" & ");
+ case "tuple":
+ return `[${(type.elements ?? []).map(typeToString).join(", ")}]`;
+ case "namedTupleMember":
+ return `${type.name}${type.isOptional ? "?" : ""}: ${typeToString(type.element)}`;
+ case "optional":
+ return `${typeToString(type.elementType)}?`;
+ case "rest":
+ return `...${typeToString(type.elementType)}`;
+ case "typeOperator":
+ return `${type.operator} ${wrap(type.target)}`;
+ case "query":
+ return `typeof ${typeToString(type.queryType)}`;
+ case "indexedAccess":
+ return `${wrap(type.objectType)}[${typeToString(type.indexType)}]`;
+ case "predicate":
+ return `${type.asserts ? "asserts " : ""}${type.name}${type.targetType ? ` is ${typeToString(type.targetType)}` : ""}`;
+ case "reflection":
+ return reflectionToString(type.declaration);
+ default:
+ return "name" in type && typeof type.name === "string" ? type.name : type.type;
+ }
+}
+
+/** An inline type: a function type, or an object type literal. */
+function reflectionToString(declaration: Declaration) {
+ const signature = declaration.signatures?.[0];
+ if (signature) {
+ return `${parametersToString(signature)} => ${typeToString(signature.type)}`;
+ }
+
+ const members = (declaration.children ?? []).map((member) => {
+ const optional = member.flags.isOptional ? "?" : "";
+ const memberSignature = member.signatures?.[0];
+ return memberSignature
+ ? `${member.name}${optional}${parametersToString(memberSignature)}: ${typeToString(memberSignature.type)}`
+ : `${member.name}${optional}: ${typeToString(member.type)}`;
+ });
+ const index = declaration.indexSignatures?.[0];
+ if (index) {
+ const [ key ] = index.parameters ?? [];
+ members.push(`[${key?.name ?? "key"}: ${typeToString(key?.type)}]: ${typeToString(index.type)}`);
+ }
+
+ return members.length ? `{ ${members.join("; ")} }` : "{}";
+}
+
+/** A type as an operand of `[]`, `&` or a type operator, in parentheses when it needs them. */
+function wrap(type: SomeType | undefined) {
+ const text = typeToString(type);
+ const needsParentheses = type?.type === "union" || type?.type === "intersection"
+ || (type?.type === "reflection" && !!type.declaration.signatures?.length);
+ return needsParentheses ? `(${text})` : text;
+}
+
+function fence(text: string) {
+ return `\`\`\`ts\n${text}\n\`\`\``;
+}
+
+function table(headers: string[], rows: string[][]) {
+ const line = (cells: string[]) => `| ${cells.map((cell) => cell.replace(/\|/g, "\\|")).join(" | ")} |`;
+ return [ line(headers), `| ${headers.map(() => "---").join(" | ")} |`, ...rows.map(line) ].join("\n");
+}
+
+function code(text: string) {
+ return text ? `\`${text}\`` : "";
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index e3bdc95ba9..c3eb365052 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -555,6 +555,9 @@ importers:
electron:
specifier: 44.9.0
version: 44.9.0([email protected])
+ typedoc:
+ specifier: 0.28.20
+ version: 0.28.20([email protected])
apps/icon-pack-builder:
dependencies: