@apify/docusaurus-plugin-typedoc-api 3.0.0

package/src/plugin/version.ts

@@ -0,0 +1,118 @@
+// BASED ON: https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-content-docs/src/versions.ts
+
+import path from 'path';
+import type { PluginOptions as DocusaurusNativePluginOptions } from '@docusaurus/plugin-content-docs';
+import {
+	CURRENT_VERSION_NAME,
+	filterVersions,
+	getDefaultVersionBanner,
+	readVersionNames,
+	VERSIONED_DOCS_DIR,
+} from '@docusaurus/plugin-content-docs/server';
+import type { LoadContext } from '@docusaurus/types';
+import { DEFAULT_PLUGIN_ID, normalizeUrl } from '@docusaurus/utils';
+import type { DocusaurusPluginTypeDocApiOptions, VersionMetadata } from '../types';
+
+type PluginOptions = DocusaurusPluginTypeDocApiOptions;
+
+export function getVersionedDocsDirPath(siteDir: string, pluginId: string): string {
+	return path.join(
+		siteDir,
+		pluginId === DEFAULT_PLUGIN_ID ? VERSIONED_DOCS_DIR : `${pluginId}_${VERSIONED_DOCS_DIR}`,
+	);
+}
+
+function getDefaultLastVersionName(versionNames: string[]): string {
+	if (versionNames.length === 1) {
+		return versionNames[0];
+	}
+
+	return versionNames.find((versionName) => versionName !== CURRENT_VERSION_NAME) ?? '';
+}
+
+function createVersionMetadata({
+	versionName,
+	versionNames,
+	lastVersionName,
+	context,
+	options,
+}: {
+	versionName: string;
+	versionNames: string[];
+	lastVersionName: string;
+	context: LoadContext;
+	options: PluginOptions;
+}): VersionMetadata {
+	const isLast = versionName === lastVersionName;
+	const versionOptions = options.versions[versionName] ?? {};
+	const versionLabel =
+		versionOptions.label ?? versionName === CURRENT_VERSION_NAME ? 'Next' : versionName;
+	let versionPathPart =
+		versionOptions.path ?? versionName === CURRENT_VERSION_NAME ? 'next' : versionName;
+
+	if (isLast) {
+		versionPathPart = '';
+	}
+
+	const versionPath = normalizeUrl([
+		context.siteConfig.baseUrl,
+		options.routeBasePath ?? 'api',
+		versionPathPart,
+	]);
+
+	return {
+		isLast: versionName === lastVersionName,
+		routePriority: versionPathPart === '' ? -1 : undefined,
+		versionBadge: versionOptions?.badge ?? versionNames.length !== 1,
+		versionBanner: getDefaultVersionBanner({
+			context,
+			lastVersionName,
+			// @ts-expect-error Ignore internal options
+			options,
+			versionName,
+			versionNames,
+		}),
+		versionClassName: versionOptions?.className ?? `api-version-${versionName}`,
+		versionLabel,
+		versionName,
+		versionPath,
+	};
+}
+
+export async function readVersionsMetadata(
+	context: LoadContext,
+	options: DocusaurusPluginTypeDocApiOptions,
+): Promise<VersionMetadata[]> {
+	// Docusaurus internals require *every* option, but the versioning
+	// does not actually use them. We are casting the types here to
+	// ignore all the missing properties.
+	const specialOptions = options as DocusaurusNativePluginOptions &
+		DocusaurusPluginTypeDocApiOptions;
+
+	const versionNamesUnfiltered = await readVersionNames(context.siteDir, {
+		...specialOptions,
+		disableVersioning: options.disableVersioning ?? false,
+		id: options.id ?? 'default',
+		includeCurrentVersion: options.includeCurrentVersion ?? true,
+	});
+	const versionNames = filterVersions(versionNamesUnfiltered, {
+		...specialOptions,
+		onlyIncludeVersions:
+			options.onlyIncludeVersions && options.onlyIncludeVersions.length > 0
+				? options.onlyIncludeVersions
+				: undefined,
+	});
+	const lastVersionName = options.lastVersion
+		? options.lastVersion
+		: getDefaultLastVersionName(versionNames);
+
+	return versionNames.map((versionName) =>
+		createVersionMetadata({
+			context,
+			lastVersionName,
+			options,
+			versionName,
+			versionNames,
+		}),
+	);
+}

package/src/types.ts

@@ -0,0 +1,165 @@
+import type { JSONOutput, TypeDocOptions } from 'typedoc';
+import type {
+	PropSidebarItem,
+	VersionBanner,
+	VersionsOptions,
+} from '@docusaurus/plugin-content-docs';
+
+export type { VersionBanner };
+
+export interface DocusaurusPluginTypeDocApiOptions
+	extends Omit<VersionsOptions, 'disableVersioning' | 'includeCurrentVersion'> {
+	banner?: string;
+	breadcrumbs?: boolean;
+	changelogName?: string;
+	changelogs?: boolean;
+	gitRefName?: string;
+	debug?: boolean;
+	exclude?: string[];
+	id?: string;
+	minimal?: boolean;
+	packageJsonName?: string;
+	packages: (PackageConfig | string)[];
+	pathToCurrentVersionTypedocJSON?: string;
+	projectRoot: string;
+	readmeName?: string;
+	readmes?: boolean;
+	removeScopes?: string[];
+	sortPackages?: (a: PackageReflectionGroup, d: PackageReflectionGroup) => number;
+	sortSidebar?: (a: string, d: string) => number;
+	tsconfigName?: string;
+	typedocOptions?: Partial<
+		Pick<
+			TypeDocOptions,
+			| 'commentStyle'
+			| 'disableSources'
+			| 'emit'
+			| 'excludeExternals'
+			| 'excludeInternal'
+			| 'excludeNotDocumented'
+			| 'excludePrivate'
+			| 'excludeProtected'
+			| 'excludeTags'
+			| 'externalPattern'
+			| 'logger'
+			| 'logLevel'
+			| 'sort'
+			| 'treatWarningsAsErrors'
+			| 'validation'
+		>
+	>;
+
+	// Versioning, based on Docusaurus
+	disableVersioning?: boolean;
+	includeCurrentVersion?: boolean;
+	routeBasePath?: string;
+}
+
+// CONFIG
+
+export interface PackageEntryConfig {
+	label: string;
+	path: string;
+}
+
+export interface PackageConfig {
+	path: string; // Folder relative to project root
+	entry?: Record<string, PackageEntryConfig | string> | string;
+	slug?: string;
+}
+
+export interface ResolvedPackageConfig {
+	entryPoints: Record<string, PackageEntryConfig>;
+	packagePath: string;
+	packageSlug: string;
+	packageName: string;
+	packageVersion: string;
+}
+
+// VERSIONING
+
+export interface VersionMetadata {
+	versionName: string; // 1.0.0
+	versionLabel: string; // Version 1.0.0
+	versionPath: string; // /baseUrl/api/1.0.0
+	versionBadge: boolean;
+	versionBanner: VersionBanner | null;
+	versionClassName: string;
+	isLast: boolean;
+	routePriority: number | undefined; // -1 for the latest
+}
+
+export interface LoadedVersion extends VersionMetadata {
+	// mainDocId: string;
+	packages: PackageReflectionGroup[];
+	sidebars: SidebarItem[];
+}
+
+export interface LoadedContent {
+	loadedVersions: LoadedVersion[];
+}
+
+// SIDEBAR / UI
+
+export type SidebarItem = PropSidebarItem;
+
+export interface ApiOptions {
+	banner: string;
+	breadcrumbs: boolean;
+	gitRefName: string;
+	minimal: boolean;
+	pluginId: string;
+	scopes: string[];
+}
+
+export interface TOCItem {
+	readonly value: string;
+	readonly id: string;
+	readonly level: number;
+}
+
+// REFLECTIONS
+
+export interface PackageReflectionGroupEntry {
+	index: boolean;
+	label: string;
+	reflection: JSONOutput.ProjectReflection;
+	urlSlug: string;
+}
+
+export interface PackageReflectionGroup {
+	entryPoints: PackageReflectionGroupEntry[];
+	packageName: string;
+	packageVersion: string;
+	changelogPath?: string;
+	readmePath?: string;
+}
+
+export interface ApiMetadata {
+	id: number;
+	name: string;
+	permalink: string;
+	previousId?: number;
+	nextId?: number;
+}
+
+export type DeclarationReflectionMap = Record<number, JSONOutput.DeclarationReflection>;
+
+declare module 'typedoc/dist/lib/serialization/schema' {
+	interface Reflection extends ApiMetadata {
+		// Not typed but used in the templates
+		declaration?: DeclarationReflection;
+		// Added by us for convenience
+		parentId?: number;
+	}
+
+	interface Type {
+		// Not typed but used in the templates
+		declaration?: DeclarationReflection;
+	}
+}
+
+declare global {
+	// eslint-disable-next-line no-var, vars-on-top
+	var typedocBuild: { count: number };
+}

package/src/utils/hierarchy.ts

@@ -0,0 +1,46 @@
+import type { JSONOutput } from 'typedoc';
+
+export interface HierarchyNode {
+	types: JSONOutput.SomeType[];
+	next?: HierarchyNode;
+	isTarget?: boolean;
+}
+
+// The JSON output does not include hierarchy information, so we need to duplicate the logic!
+// https://github.com/TypeStrong/typedoc/blob/master/src/lib/converter/plugins/TypePlugin.ts#L98
+export function createHierarchy(reflection: JSONOutput.DeclarationReflection) {
+	let root!: HierarchyNode;
+	let hierarchy!: HierarchyNode;
+
+	function push(types: JSONOutput.SomeType[]) {
+		const level: HierarchyNode = { types };
+
+		if (hierarchy) {
+			hierarchy.next = level;
+			hierarchy = level;
+		} else {
+			root = level;
+			hierarchy = level;
+		}
+	}
+
+	if (reflection.extendedTypes) {
+		push(reflection.extendedTypes);
+	}
+
+	push([
+		{
+			id: reflection.id,
+			name: reflection.name,
+			type: 'reference',
+		},
+	]);
+
+	hierarchy.isTarget = true;
+
+	if (reflection.extendedBy) {
+		push(reflection.extendedBy);
+	}
+
+	return root;
+}

package/src/utils/icons.ts

@@ -0,0 +1,103 @@
+/* eslint-disable no-fallthrough */
+
+import type { ReflectionKind } from 'typedoc';
+
+// We have to map these manually instead of using the `ReflectionKind` enum,
+// otherwise the `typedoc` package ends up in the bundle and crashes.
+const KIND_ICONS: Record<ReflectionKind, string> = {
+	1: 'project', // Project
+	2: 'package', // Module
+	4: 'symbol-namespace', // Namespace
+	8: 'symbol-enum', // Enum
+	16: 'symbol-enum-member', // EnumMember
+	32: 'symbol-variable', // Variable
+	64: 'symbol-function', // Function
+	128: 'symbol-class', // Class
+	256: 'symbol-interface', // Interface
+	512: 'symbol-constructor', // Constructor
+	1024: 'symbol-property', // Property
+	2048: 'symbol-method', // Method
+	4096: 'symbol-method', // CallSignature
+	8192: 'bracket-dot', // IndexSignature
+	16_384: 'symbol-method', // ConstructorSignature
+	32_768: 'symbol-property', // Parameter
+	65_536: 'symbol-key', // TypeLiteral
+	131_072: 'symbol-type-parameter', // TypeParameter
+	262_144: 'symbol-field', // Accessor
+	524_288: 'symbol-field', // GetSignature
+	1_048_576: 'symbol-field', // SetSignature
+	2_097_152: 'bracket', // ObjectLiteral
+	4_194_304: 'symbol-parameter', // TypeAlias
+	8_388_608: 'references', // Reference
+};
+
+export function getKindIcon(kind: ReflectionKind, name: string): string {
+	let icon = KIND_ICONS[kind];
+
+	// Use event icon when property starts with "on"
+	if (kind === 1024 && name.match(/^on[A-Z]/)) {
+		icon = 'symbol-event';
+	}
+
+	return icon;
+}
+
+// eslint-disable-next-line complexity
+export function getKindIconColor(kind: ReflectionKind): string {
+	switch (kind) {
+		// Function
+		case 64:
+		// Constructor
+		case 512:
+		// Method
+		case 2048:
+		// CallSignature
+		case 4096:
+		// ConstructorSignature
+		case 16_384:
+		// Accessor
+		case 262_144:
+			return 'var(--ifm-color-info)';
+
+		// EnumMember
+		case 16:
+		// Variable
+		case 32:
+		// Property
+		case 1024:
+		// GetSignature
+		case 524_288:
+		// SetSignature
+		case 1_048_576:
+			return 'var(--ifm-color-success)';
+
+		// Namespace
+		case 4:
+		// Class
+		case 128:
+			return 'var(--ifm-color-warning)';
+
+		// Enum
+		case 8:
+		// Interface
+		case 256:
+		// TypeAlias
+		case 4_194_304:
+			return 'var(--ifm-color-danger)';
+
+		default:
+			return 'inherit';
+	}
+}
+
+export function getKindIconHtml(kind: ReflectionKind, name: string): string {
+	const icon = getKindIcon(kind, name);
+
+	if (!icon) {
+		return '';
+	}
+
+	const color = getKindIconColor(kind);
+
+	return `<i class="codicon codicon-${icon}" style="color:${color};"></i>`;
+}

package/src/utils/links.ts

@@ -0,0 +1,10 @@
+export function removeScopes(text: string, scopes: string[]): string {
+	if (scopes.length === 0) {
+		return text;
+	}
+
+	return scopes.reduce(
+		(value, scope) => value.replace(new RegExp(`^(${scope}-|@${scope}/)`), ''),
+		text,
+	);
+}

package/src/utils/markdown.ts

@@ -0,0 +1,82 @@
+import type { PropVersionMetadata } from '@docusaurus/plugin-content-docs';
+import type { DeclarationReflectionMap } from '../types';
+
+function splitLinkText(text: string): { caption: string; target: string } {
+	let splitIndex = text.indexOf('|');
+
+	if (splitIndex === -1) {
+		splitIndex = text.search(/\s/);
+	}
+
+	if (splitIndex !== -1) {
+		return {
+			caption: text
+				.slice(splitIndex + 1)
+				.replace(/\n+/, ' ')
+				.trim(),
+			target: text.slice(0, Math.max(0, splitIndex)).trim(),
+		};
+	}
+
+	return {
+		caption: text,
+		target: text,
+	};
+}
+
+function findReflectionWithMatchingTarget(
+	reflections: DeclarationReflectionMap,
+	symbol: string,
+	member?: string,
+) {
+	return Object.values(reflections).find((ref) => {
+		if (ref.name !== symbol) {
+			return false;
+		}
+
+		return member ? ref.children?.some((child) => child.name === member) : true;
+	});
+}
+
+function replaceApiLinks(
+	reflections: DeclarationReflectionMap,
+): (match: string, tagName: string, content: string) => string {
+	return (match: string, tagName: string, content: string) => {
+		const { caption, target } = splitLinkText(content);
+		const [symbol, member] = target.split('.');
+		const reflection = findReflectionWithMatchingTarget(reflections, symbol, member);
+		const label = tagName === 'linkcode' ? `\`${caption}\`` : caption;
+
+		if (!reflection?.permalink) {
+			return label;
+		}
+
+		return `[${label}](${reflection.permalink}${member ? `#${member}` : ''})`;
+	};
+}
+
+function replaceDocLinks(
+	currentVersion: PropVersionMetadata,
+): (match: string, content: string) => string {
+	return (match: string, content: string) => {
+		const { caption, target } = splitLinkText(content);
+		const version = currentVersion.version === 'current' ? 'next' : currentVersion.version;
+
+		// TODO: Handle `routeBasePath`? Something else besides "docs"?
+		const url = currentVersion.isLast ? `/docs/${target}` : `/docs/${version}/${target}`;
+
+		return `[${caption}](${url})`;
+	};
+}
+
+// TypeDoc JSON output does not replace links, so we need to do this manually.
+// @see https://github.com/TypeStrong/typedoc/blob/master/src/lib/output/plugins/MarkedLinksPlugin.ts
+export function replaceLinkTokens(
+	markdown: string,
+	reflections: DeclarationReflectionMap,
+	currentVersion: PropVersionMetadata,
+) {
+	return markdown
+		.replace(/{@(link|linkcode|linkplain|apilink)\s+([^}]+?)}/gi, replaceApiLinks(reflections))
+		.replace(/{@doclink\s+([^}]+?)}/gi, replaceDocLinks(currentVersion));
+}

package/src/utils/visibility.ts

@@ -0,0 +1,31 @@
+import type { JSONOutput } from 'typedoc';
+import type { DeclarationReflectionMap } from '../types';
+
+// https://github.com/TypeStrong/typedoc/blob/master/src/lib/output/themes/DefaultTheme.ts#L264
+export function hasOwnDocument(id: number, reflections: DeclarationReflectionMap): boolean {
+	const reflection = reflections[id];
+
+	return Boolean(reflection?.permalink && !reflection.permalink.includes('#'));
+}
+
+// https://github.com/TypeStrong/typedoc/blob/2103f347c9cba40fcaa1f67e36f7cea0bdea2f0f/src/lib/models/ReflectionCategory.ts#L44
+export function allCategoryChildrenHaveOwnDocument(
+	category: JSONOutput.ReflectionCategory,
+	reflections: DeclarationReflectionMap,
+): boolean {
+	let onlyOwnDocuments = true;
+
+	category.children?.forEach((child) => {
+		onlyOwnDocuments &&= hasOwnDocument(child, reflections);
+	});
+
+	return onlyOwnDocuments;
+}
+
+// https://github.com/TypeStrong/typedoc/blob/2103f347c9cba40fcaa1f67e36f7cea0bdea2f0f/src/lib/models/ReflectionGroup.ts#L81
+export function allGroupChildrenHaveOwnDocument(
+	group: JSONOutput.ReflectionGroup,
+	reflections: DeclarationReflectionMap,
+): boolean {
+	return Boolean(group.children?.every((child) => hasOwnDocument(child, reflections)));
+}