@apify/docusaurus-plugin-typedoc-api 4.4.12 → 5.1.0

package/src/plugin/python/transformation.ts

@@ -86,6 +86,19 @@ export class SymbolIdTracker {
 };
 
 export class DocspecTransformer {
+	/**
+	 * Maps Google-style docstring section names to Docusaurus admonition types.
+	 * Only sections that semantically match admonition purposes are included.
+	 * Sections like Raises, Yields, Attributes are technical documentation, not admonitions.
+	 */
+	private static readonly SECTION_TO_ADMONITION: Record<string, string> = {
+		Danger: 'danger',
+		Info: 'info',
+		Note: 'note',
+		Tip: 'tip',
+		Warning: 'warning',
+	};
+
 	private pythonTypeResolver: PythonTypeResolver;
 
 	private inheritanceGraph: InheritanceGraph;
@@ -444,12 +457,42 @@ export class DocspecTransformer {
 		return { filePathInRepo };
 	}
 
+	/**
+	 * Converts a docstring section to Docusaurus admonition markdown format.
+	 */
+	private sectionToAdmonition(sectionName: string, content: unknown[]): string {
+		const admonitionType = DocspecTransformer.SECTION_TO_ADMONITION[sectionName];
+		if (!admonitionType) {
+			return '';
+		}
+
+		const contentText = content
+			.map((item) => {
+				if (typeof item === 'string') {
+					return item;
+				}
+				if (typeof item === 'object' && item !== null && 'desc' in item) {
+					const obj = item as { param?: string; desc: string };
+					return obj.param ? `**${obj.param}**: ${obj.desc}` : obj.desc;
+				}
+				return '';
+			})
+			.filter(Boolean)
+			.join('\n');
+
+		if (!contentText) {
+			return '';
+		}
+
+		return `:::${admonitionType} ${sectionName}\n${contentText}\n:::`;
+	}
+
 	/**
 	 * If possible, parses the `.docstring` property of the passed object. If the docstring is a stringified JSON object,
 	 * it extracts the `args` and `returns` sections and adds them to the returned object.
 	 *
-	 * TODO
-	 * This structure is created in the `google` docstring format, which is a JSON object with the following structure:
+	 * The docstring format is a JSON object with a `content` array that contains interleaved text strings
+	 * and section objects, preserving the original order from the docstring.
 	 */
 	private parseDocstring(docspecMember: DocspecObject): TypeDocDocstring {
 		const docstring: TypeDocDocstring = { text: docspecMember.docstring?.content ?? '' };
@@ -457,21 +500,52 @@ export class DocspecTransformer {
 		try {
 			const parsedDocstring = JSON.parse(docstring.text) as DocspecDocstring;
 
-			docstring.text = parsedDocstring.text;
-			const parsedArguments = (parsedDocstring.sections?.find(
-				(section) => Object.keys(section)[0] === 'Arguments',
-			)?.Arguments ?? []) as DocspecDocstring['args'];
+			// Build the text output by processing content items in order
+			const textParts: string[] = [];
 
-			docstring.args =
-				parsedArguments?.reduce<Record<string, string>>((acc, arg) => {
-					acc[arg.param] = arg.desc;
-					return acc;
-				}, {}) ?? {};
-
-			const returnTypes =
-				docstring.sections?.find((section) => Object.keys(section)[0] === 'Returns')?.Returns ?? [];
+			for (const item of parsedDocstring.content ?? []) {
+				if (typeof item === 'string') {
+					// Regular text content
+					textParts.push(item);
+				} else {
+					// Section object
+					const sectionName = Object.keys(item)[0];
+					const sectionContent = item[sectionName] as unknown[];
+
+					if (sectionName === 'Arguments') {
+						// Extract arguments for parameter documentation
+						const parsedArguments = sectionContent as { param: string; desc: string }[];
+						docstring.args =
+							parsedArguments?.reduce<Record<string, string>>((acc, arg) => {
+								acc[arg.param] = arg.desc;
+								return acc;
+							}, {}) ?? {};
+					} else if (sectionName === 'Returns') {
+						// Extract return type documentation
+						docstring.returns = sectionContent
+							.map((returnsItem) => {
+								if (typeof returnsItem === 'string') {
+									return returnsItem;
+								}
+								if (typeof returnsItem === 'object' && returnsItem !== null && 'param' in returnsItem && 'desc' in returnsItem) {
+									const obj = returnsItem as { param: string; desc: string };
+									return `${obj.param}: ${obj.desc}`;
+								}
+								return '';
+							})
+							.filter(Boolean)
+							.join('\n');
+					} else {
+						// Convert other sections to admonitions inline
+						const admonition = this.sectionToAdmonition(sectionName, sectionContent);
+						if (admonition) {
+							textParts.push(admonition);
+						}
+					}
+				}
+			}
 
-			docstring.returns = returnTypes.join('\n');
+			docstring.text = textParts.join('\n\n');
 		} catch {
 			// Do nothing
 		}

package/src/plugin/python/types.ts

@@ -71,11 +71,10 @@ export interface TypeDocDocstring {
 	sections?: Record<string, any[]>[];
 }
 
+export type DocspecDocstringContentItem = Record<string, any[]> | string;
+
 export interface DocspecDocstring {
-	text: string;
-	returns?: string;
-	args?: { param: string; desc: string }[];
-	sections?: Record<string, any[]>[];
+	content: DocspecDocstringContentItem[];
 }
 
 export type TypeDocType =

package/src/plugin/sidebar.ts

@@ -7,7 +7,7 @@ import type {
 	TSDDeclarationReflection,
 	TSDDeclarationReflectionMap,
 } from '../types';
-import { removeScopes } from '../utils/links';
+import { removeScopes } from '../utils/removeScopes';
 import { createReflectionMap } from './data';
 
 export function groupSidebarItems(

package/src/plugin/url.ts

@@ -1,4 +1,4 @@
-import path from 'path';
+import path from 'node:path';
 import { JSONOutput, ReflectionKind } from 'typedoc';
 import type { ResolvedPackageConfig } from '../types';
 

package/src/plugin/version.ts

@@ -1,6 +1,6 @@
 // BASED ON: https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-content-docs/src/versions.ts
 
-import path from 'path';
+import path from 'node:path';
 import type { PluginOptions as DocusaurusNativePluginOptions } from '@docusaurus/plugin-content-docs';
 import {
 	CURRENT_VERSION_NAME,

package/src/utils/links.ts

@@ -1,17 +1,6 @@
-import fs from 'fs';
+import fs from 'node:fs';
 import { TypedocJSONFile } from '../types';
 
-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,
-	);
-}
-
 export function injectGitRevision(typedocJsonFilePath: string, gitRevision: string): void {
 	const typedocJson = JSON.parse(fs.readFileSync(typedocJsonFilePath, 'utf8')) as TypedocJSONFile;
 

package/src/utils/removeScopes.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,
+	);
+}