@apify/docusaurus-plugin-typedoc-api 3.0.0

package/src/plugin/data.ts

@@ -0,0 +1,389 @@
+import fs from 'fs';
+import path from 'path';
+import * as TypeDoc from 'typedoc';
+import { JSONOutput, ReflectionKind } from 'typedoc';
+import ts from 'typescript';
+import { normalizeUrl } from '@docusaurus/utils';
+import type {
+	DeclarationReflectionMap,
+	DocusaurusPluginTypeDocApiOptions,
+	PackageReflectionGroup,
+	ResolvedPackageConfig,
+} from '../types';
+import { migrateToVersion0230 } from './structure/0.23';
+import { getKindSlug, getPackageSlug, joinUrl } from './url';
+
+function shouldEmit(projectRoot: string, tsconfigPath: string) {
+	// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+	const { config, error } = ts.readConfigFile(tsconfigPath, (name) =>
+		fs.readFileSync(name, 'utf8'),
+	);
+
+	if (error) {
+		throw new Error(`Failed to load ${tsconfigPath}`);
+	}
+
+	const result = ts.parseJsonConfigFileContent(config, ts.sys, projectRoot, {}, tsconfigPath);
+
+	if (result.errors.length > 0) {
+		throw new Error(`Failed to parse ${tsconfigPath}`);
+	}
+
+	return result.projectReferences && result.projectReferences.length > 0 ? 'docs' : 'none';
+}
+
+// Persist build state as a global, since the plugin is re-evaluated every hot reload.
+// Because of this, we can't use state in the plugin or module scope.
+if (!global.typedocBuild) {
+	global.typedocBuild = { count: 0 };
+}
+
+export async function generateJson(
+	projectRoot: string,
+	entryPoints: string[],
+	outFile: string,
+	options: DocusaurusPluginTypeDocApiOptions,
+): Promise<boolean> {
+	/* eslint-disable sort-keys */
+
+	// Running the TypeDoc compiler is pretty slow...
+	// We should only load on the 1st build, and use cache for subsequent reloads.
+	if (global.typedocBuild.count > 0 && fs.existsSync(outFile)) {
+		return true;
+	}
+
+	const app = new TypeDoc.Application();
+	const tsconfig = path.join(projectRoot, options.tsconfigName!);
+
+	app.options.addReader(new TypeDoc.TSConfigReader());
+	app.options.addReader(new TypeDoc.TypeDocReader());
+
+	app.bootstrap({
+		skipErrorChecking: true,
+		// Only emit when using project references
+		emit: shouldEmit(projectRoot, tsconfig),
+		// Only document the public API by default
+		excludeExternals: true,
+		excludeInternal: true,
+		excludePrivate: true,
+		excludeProtected: true,
+		// Enable verbose logging when debugging
+		logLevel: options.debug ? 'Verbose' : 'Info',
+		inlineTags: [
+			'@link',
+			'@inheritDoc',
+			'@label',
+			'@linkcode',
+			'@linkplain',
+			'@apilink',
+			'@doclink',
+		] as `@${string}`[],
+		...options.typedocOptions,
+		// Control how config and packages are detected
+		tsconfig,
+		entryPoints: entryPoints.map((ep) => path.join(projectRoot, ep)),
+		entryPointStrategy: 'expand',
+		exclude: options.exclude,
+		// We use a fake category title so that we can fallback to the parent group
+		defaultCategory: 'CATEGORY',
+	});
+
+	const project = app.convert();
+
+	if (project) {
+		await app.generateJson(project, outFile);
+
+		global.typedocBuild.count += 1;
+
+		return true;
+	}
+
+	return false;
+}
+
+export function createReflectionMap(
+	items: JSONOutput.DeclarationReflection[] = [],
+): DeclarationReflectionMap {
+	const map: DeclarationReflectionMap = {};
+
+	items.forEach((item) => {
+		map[item.id] = item;
+	});
+
+	return map;
+}
+
+export function loadPackageJsonAndDocs(
+	initialDir: string,
+	pkgFileName: string = 'package.json',
+	readmeFileName: string = 'README.md',
+	changelogFileName: string = 'CHANGELOG.md',
+) {
+	let currentDir = initialDir;
+
+	while (!fs.existsSync(path.join(currentDir, pkgFileName))) {
+		currentDir = path.dirname(currentDir);
+	}
+
+	const readmePath = path.join(currentDir, readmeFileName);
+	const changelogPath = path.join(currentDir, changelogFileName);
+
+	return {
+		packageJson: JSON.parse(fs.readFileSync(path.join(currentDir, pkgFileName), 'utf8')) as {
+			name: string;
+			version: string;
+		},
+		readmePath: fs.existsSync(readmePath) ? readmePath : '',
+		changelogPath: fs.existsSync(changelogPath) ? changelogPath : '',
+	};
+}
+
+export function addMetadataToReflections(
+	project: JSONOutput.ProjectReflection,
+	packageSlug: string,
+	urlPrefix: string,
+): JSONOutput.ProjectReflection {
+	const permalink = `/${joinUrl(urlPrefix, packageSlug)}`;
+
+	if (project.children) {
+		// eslint-disable-next-line no-param-reassign
+		project.children = project.children.map((child) => {
+			migrateToVersion0230(child);
+
+			const kindSlugPart = getKindSlug(child);
+			const childSlug = kindSlugPart ? `/${kindSlugPart}/${child.name}` : `#${child.name}`;
+			const childPermalink = permalink + childSlug;
+
+			// We need to go another level deeper and only use fragments
+			if (child.kind === ReflectionKind.Namespace && child.children) {
+				// eslint-disable-next-line no-param-reassign
+				child.children = child.children.map((grandChild) => ({
+					...grandChild,
+					permalink: normalizeUrl([`${childPermalink}#${grandChild.name}`]),
+				}));
+			}
+
+			return {
+				...child,
+				permalink: normalizeUrl([childPermalink]),
+			};
+		});
+	}
+
+	return {
+		...project,
+		permalink: normalizeUrl([permalink]),
+	};
+}
+
+function mergeReflections(base: JSONOutput.ProjectReflection, next: JSONOutput.ProjectReflection) {
+	if (Array.isArray(base.children) && Array.isArray(next.children)) {
+		base.children.push(...next.children);
+	}
+
+	if (Array.isArray(base.groups) && Array.isArray(next.groups)) {
+		next.groups.forEach((group) => {
+			const baseGroup = base.groups?.find((g) => g.title === group.title);
+
+			if (baseGroup) {
+				baseGroup.children?.push(...(group.children ?? []));
+			} else {
+				base.groups?.push(group);
+			}
+		});
+
+		// We can remove refs since were merging all reflections into one
+		// eslint-disable-next-line no-param-reassign
+		base.groups = base.groups.filter((group) => group.title !== 'References');
+	}
+}
+
+function sortReflectionGroups(reflections: JSONOutput.ProjectReflection[]) {
+	reflections.forEach((reflection) => {
+		const map = createReflectionMap(reflection.children);
+		const sort = (a: number, b: number) => (map[a].name < map[b].name ? -1 : 1);
+
+		reflection.categories?.forEach((category) => {
+			category.children?.sort(sort);
+		});
+
+		reflection.groups?.forEach((group) => {
+			group.children?.sort(sort);
+
+			group.categories?.forEach((category) => {
+				category.children?.sort(sort);
+			});
+		});
+	});
+}
+
+function matchesEntryPoint(
+	sourceFile: string,
+	entryPoint: string,
+	{ deep, single }: { deep: boolean; single: boolean },
+): boolean {
+	// Single package
+	if (single) {
+		return (
+			// src/index.ts === src/index.ts
+			(!deep && sourceFile === entryPoint) ||
+			// index.ts === src/index.ts
+			(!deep && sourceFile === path.basename(entryPoint)) ||
+			// some/deep/file.ts === ...
+			deep
+		);
+	}
+
+	// Multiple packages
+	return (
+		// packages/foo/src/index.ts === packages/foo/src/index.ts
+		// foo/src/index.ts ~ packages/foo/src/index.ts
+		(!deep && (sourceFile === entryPoint || entryPoint.endsWith(sourceFile))) ||
+		// packages/foo/src/some/deep/file.ts === packages/foo/src/
+		(deep && sourceFile.startsWith(entryPoint))
+	);
+}
+
+function extractReflectionModules(
+	project: JSONOutput.ProjectReflection,
+	isSinglePackage: boolean,
+): JSONOutput.ProjectReflection[] {
+	const modules: JSONOutput.ProjectReflection[] = [];
+
+	const inheritChildren = () => {
+		project.children?.forEach((child) => {
+			if (child.kind === ReflectionKind.Module) {
+				modules.push(child);
+			}
+		});
+	};
+
+	// Single packages are extremely difficult, as the TypeDoc structure is
+	// different for every kind of package entry point pattern
+	if (isSinglePackage) {
+		const hasNoModules = project.children?.every((child) => child.kind !== ReflectionKind.Module);
+
+		if (hasNoModules) {
+			// No "module" children:
+			//	- Polyrepos
+			//	- Monorepos with 1 package
+			modules.push(project);
+		} else {
+			// Has "module" children:
+			//	- Polyrepos with deep imports
+			//	- Polyrepos with multi-imports
+			//	- Monorepos
+			inheritChildren();
+		}
+
+		// Multiple packages are extremely simple, as every package is a module reflection
+		// as a child on the top-level project reflection
+	} else {
+		inheritChildren();
+	}
+
+	return modules;
+}
+
+export function flattenAndGroupPackages(
+	packageConfigs: ResolvedPackageConfig[],
+	project: JSONOutput.ProjectReflection,
+	urlPrefix: string,
+	options: DocusaurusPluginTypeDocApiOptions,
+	versioned: boolean = false,
+): PackageReflectionGroup[] {
+	const isSinglePackage = packageConfigs.length === 1;
+	const modules = extractReflectionModules(project, isSinglePackage);
+
+	// Loop through every TypeDoc module and group based on package and entry point
+	const packages: Record<string, PackageReflectionGroup> = {};
+	const packagesWithDeepImports: JSONOutput.ProjectReflection[] = [];
+
+	modules.forEach((mod) => {
+		const relSourceFile = mod.sources?.[0]?.fileName ?? '';
+
+		packageConfigs.some((cfg) =>
+			Object.entries(cfg.entryPoints).some(([importPath, entry]) => {
+				const relEntryPoint = joinUrl(cfg.packagePath, entry.path);
+				const isUsingDeepImports = !entry.path.match(/\.tsx?$/);
+
+				if (
+					!matchesEntryPoint(relSourceFile, relEntryPoint, {
+						deep: isUsingDeepImports,
+						single: isSinglePackage,
+					})
+				) {
+					return false;
+				}
+
+				// We have a matching entry point, so store the record
+				if (!packages[cfg.packagePath]) {
+					const { packageJson, readmePath, changelogPath } = loadPackageJsonAndDocs(
+						path.join(options.projectRoot, cfg.packagePath),
+						options.packageJsonName,
+						options.readmeName,
+						options.changelogName,
+					);
+
+					packages[cfg.packagePath] = {
+						entryPoints: [],
+						packageName: (versioned && cfg.packageName) || packageJson.name,
+						packageVersion: (versioned && cfg.packageVersion) || packageJson.version,
+						readmePath,
+						changelogPath,
+					};
+
+					// eslint-disable-next-line no-param-reassign
+					cfg.packageName = packages[cfg.packagePath].packageName;
+					// eslint-disable-next-line no-param-reassign
+					cfg.packageVersion = packages[cfg.packagePath].packageVersion;
+				}
+
+				// Add metadata to package and children reflections
+				const urlSlug = getPackageSlug(cfg, importPath, isSinglePackage);
+				const reflection = addMetadataToReflections(mod, urlSlug, urlPrefix);
+				const existingEntry = packages[cfg.packagePath].entryPoints.find(
+					(ep) => ep.urlSlug === urlSlug,
+				);
+
+				if (existingEntry) {
+					if (isUsingDeepImports) {
+						mergeReflections(existingEntry.reflection, reflection);
+					} else {
+						// eslint-disable-next-line no-console
+						console.error(`Entry point ${urlSlug} already defined. How did you get here?`);
+					}
+				} else {
+					packages[cfg.packagePath].entryPoints.push({
+						index: importPath === 'index',
+						label: entry.label,
+						reflection,
+						urlSlug,
+					});
+
+					if (isUsingDeepImports) {
+						packagesWithDeepImports.push(reflection);
+					}
+				}
+
+				// Update the reflection name since its useless
+				reflection.name =
+					importPath === 'index'
+						? packages[cfg.packagePath].packageName
+						: joinUrl(packages[cfg.packagePath].packageName, importPath);
+
+				return true;
+			}),
+		);
+	});
+
+	// Since we merged multiple reflections together, we'll need to sort groups manually
+	sortReflectionGroups(packagesWithDeepImports);
+
+	// Sort packages by name
+	return Object.values(packages).sort((a, b) => a.packageName.localeCompare(b.packageName));
+}
+
+export function formatPackagesWithoutHostInfo(packages: PackageReflectionGroup[]) {
+	return packages.map(({ changelogPath, readmePath, ...pkg }) => pkg);
+}

package/src/plugin/sidebar.ts

@@ -0,0 +1,139 @@
+import { JSONOutput } from 'typedoc';
+import { normalizeUrl } from '@docusaurus/utils';
+import type {
+	DeclarationReflectionMap,
+	DocusaurusPluginTypeDocApiOptions,
+	PackageReflectionGroup,
+	SidebarItem,
+} from '../types';
+import { removeScopes } from '../utils/links';
+import { createReflectionMap } from './data';
+
+export function groupSidebarItems(
+	map: DeclarationReflectionMap,
+	groups: JSONOutput.ReflectionGroup[],
+): SidebarItem[] {
+	const items: SidebarItem[] = [];
+	const sortedGroups = [...groups].sort((a, b) => a.title.localeCompare(b.title));
+
+	function getLastItemInGroup(index: number) {
+		const length = sortedGroups[index]?.children?.length;
+
+		return length ? sortedGroups[index]?.children?.[length - 1] : undefined;
+	}
+
+	sortedGroups.forEach((group, groupIndex) => {
+		const { children } = group;
+
+		if (!children || children.length === 0) {
+			return;
+		}
+
+		items.push({
+			collapsed: true,
+			collapsible: true,
+			items: children.map((id, index) => {
+				const child = map[id];
+
+				// We map previous/next from here since the sidebar is grouped by type,
+				// and we only want to link based on this order.
+				const previousId = index === 0 ? getLastItemInGroup(groupIndex - 1) : children[index - 1];
+				const nextId =
+					index === children.length - 1
+						? groups[groupIndex + 1]?.children?.[0]
+						: children[index + 1];
+
+				if (previousId) {
+					child.previousId = previousId;
+				}
+
+				if (nextId) {
+					child.nextId = nextId;
+				}
+
+				return {
+					href: child.permalink,
+					label: child.name,
+					type: 'link',
+				};
+			}),
+			label: group.title,
+			type: 'category',
+		});
+	});
+
+	return items;
+}
+
+export function extractReflectionSidebar(pkg: JSONOutput.ProjectReflection): SidebarItem[] {
+	return pkg.groups ? groupSidebarItems(createReflectionMap(pkg.children), pkg.groups) : [];
+}
+
+export function extractSidebar(
+	packages: PackageReflectionGroup[],
+	scopes: string[],
+	changelogs: boolean,
+	sortSidebar: NonNullable<DocusaurusPluginTypeDocApiOptions['sortSidebar']>,
+): SidebarItem[] {
+	if (packages.length === 0) {
+		return [];
+	}
+
+	const items: SidebarItem[] = packages.map((pkg) => {
+		let subItems: SidebarItem[] = [];
+
+		pkg.entryPoints.forEach((entry) => {
+			// Index entry point should always bubble up reflection groups
+			if (entry.index) {
+				subItems.push(...extractReflectionSidebar(entry.reflection));
+				// Otherwise nest non-index entry points behind categories
+			} else {
+				subItems.push({
+					collapsed: true,
+					collapsible: true,
+					items: extractReflectionSidebar(entry.reflection),
+					label: entry.label,
+					type: 'category',
+				});
+			}
+		});
+
+		// Always include the overview as the 1st item
+		const indexHref = pkg.entryPoints.find((entry) => entry.index)?.reflection.permalink ?? '';
+
+		subItems = subItems.sort((a, d) =>
+			sortSidebar('label' in a ? a.label : '', 'label' in d ? d.label : ''),
+		);
+
+		subItems.unshift({
+			href: indexHref,
+			label: 'Overview',
+			type: 'link',
+		});
+
+		if (pkg.changelogPath && changelogs) {
+			subItems.push({
+				href: normalizeUrl([indexHref, 'changelog']),
+				label: 'Changelog',
+				type: 'link',
+			});
+		}
+
+		return {
+			collapsed: true,
+			collapsible: true,
+			items: subItems,
+			label: removeScopes(pkg.packageName, scopes),
+			type: 'category',
+		} as const;
+	});
+
+	const sidebar = items.filter((item) => 'items' in item && items.length > 0);
+
+	// Collapse sidebar when only 1 package
+	if (packages.length === 1 && sidebar.length === 1 && sidebar[0].type === 'category') {
+		return sidebar[0].items;
+	}
+
+	return sidebar;
+}

package/src/plugin/structure/0.23.ts

@@ -0,0 +1,58 @@
+/* eslint-disable no-param-reassign */
+
+import { JSONOutput } from 'typedoc';
+
+interface OldComment {
+	shortText?: string;
+	text?: string;
+	tags?: { tag: string; text: string }[];
+}
+
+interface OldDeclarationReflection {
+	typeParameter?: JSONOutput.TypeParameterReflection[];
+}
+
+// https://github.com/TypeStrong/typedoc/releases/tag/v0.23.0
+// https://github.com/milesj/docusaurus-plugin-typedoc-api/pull/50
+export function migrateToVersion0230(reflection: JSONOutput.DeclarationReflection) {
+	if (Array.isArray(reflection.getSignature)) {
+		// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+		reflection.getSignature = reflection.getSignature[0];
+	}
+
+	if (Array.isArray(reflection.setSignature)) {
+		// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+		reflection.setSignature = reflection.setSignature[0];
+	}
+
+	if ('typeParameter' in reflection) {
+		reflection.typeParameters = (reflection as OldDeclarationReflection).typeParameter;
+	}
+
+	if (
+		reflection.comment &&
+		('shortText' in reflection.comment ||
+			'text' in reflection.comment ||
+			'tags' in reflection.comment)
+	) {
+		const comment = reflection.comment as OldComment;
+		const summary: JSONOutput.CommentDisplayPart[] = [];
+
+		if (comment.shortText) {
+			summary.push({ kind: 'text', text: comment.shortText });
+		}
+
+		if (comment.text) {
+			summary.push({ kind: 'text', text: comment.text });
+		}
+
+		reflection.comment = {
+			blockTags: comment.tags?.map((tag) => ({
+				content: [{ kind: 'text', text: tag.text }],
+				name: tag.tag,
+				tag: `@${tag.tag}`,
+			})),
+			summary,
+		};
+	}
+}

package/src/plugin/url.ts

@@ -0,0 +1,49 @@
+import path from 'path';
+import { JSONOutput, ReflectionKind } from 'typedoc';
+import type { ResolvedPackageConfig } from '../types';
+
+export function joinUrl(...paths: string[]): string {
+	return path.join(...paths).replace(/\\/g, '/');
+}
+
+export function getKindSlug(decl: JSONOutput.DeclarationReflection): string {
+	switch (decl.kind) {
+		case ReflectionKind.Module:
+			return 'package';
+		case ReflectionKind.Namespace:
+			return 'namespace';
+		case ReflectionKind.Enum:
+			return 'enum';
+		case ReflectionKind.Function:
+			return 'function';
+		case ReflectionKind.Class:
+			return 'class';
+		case ReflectionKind.Interface:
+			return 'interface';
+		default:
+			return '';
+	}
+}
+
+export function getPackageSlug(
+	pkgConfig: ResolvedPackageConfig,
+	importPath: string,
+	isSinglePackage: boolean,
+): string {
+	// Monorepo with 1 package has special handling
+	if (isSinglePackage && pkgConfig.packageSlug !== '.') {
+		return '.';
+	}
+
+	// packages/foo -> foo
+	const slug = pkgConfig.packageSlug ?? path.basename(pkgConfig.packagePath);
+
+	// bar/baz -> bar-baz
+	const importName = importPath.replace(/\\/g, '-');
+
+	if (importName === 'index') {
+		return slug;
+	}
+
+	return `${slug}-${importName}`;
+}