Build your personal knowledge base with Trilium Notes
TypeScript electronelectron-appknowledge-baseknowledge-graphknowledge-managementknowledge-management-graphlocal-firstnote-managmentnote-takernote-takingnotebooknotesnotes-apppersonal-knowledge-basepersonal-wikiscriptableself-hostedself-hostingwiki
feat(docs): generate User Guide pages from TypeScript declarations
Elian Doran03f65bb73630
diff --git a/apps/edit-docs/package.json b/apps/edit-docs/package.jsonindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.yamlindex e3bdc95ba9..c3eb365052 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -555,6 +555,9 @@ importers:electron:specifier: 44.9.0version: 44.9.0([email protected])+ typedoc:+ specifier: 0.28.20+ version: 0.28.20([email protected])apps/icon-pack-builder:dependencies: