@apify/docusaurus-plugin-typedoc-api 4.2.5 → 4.2.7

package/src/components/MemberSignatureBody.tsx

@@ -1,8 +1,12 @@
 // https://github.com/TypeStrong/typedoc-default-themes/blob/master/src/default/partials/member.signature.body.hbs
 
-import type { JSONOutput } from 'typedoc';
+import { Fragment, useContext } from 'react'
+import type { JSONOutput, Models } from 'typedoc';
+import { type GlobalData } from '@docusaurus/types';
+import { usePluginData } from '@docusaurus/useGlobalData';
 import { useMinimalLayout } from '../hooks/useMinimalLayout';
 import type { TSDSignatureReflection } from '../types';
+import { ApiDataContext } from './ApiDataContext';
 import { Comment, hasComment } from './Comment';
 import { CommentBadges, isCommentWithModifiers } from './CommentBadges';
 import { DefaultValue } from './DefaultValue';
@@ -60,6 +64,46 @@ export function MemberSignatureBody({ hideSources, sig }: MemberSignatureBodyPro
 	const showParams = !minimal && sig.parameters && sig.parameters.length > 0;
 	const showReturn = !minimal && sig.type;
 
+	const { reflections } = useContext(ApiDataContext);
+	const { isPython } = usePluginData('docusaurus-plugin-typedoc-api') as GlobalData;
+
+
+	if (isPython) {
+		// eslint-disable-next-line
+		sig.parameters = sig.parameters?.reduce<typeof sig.parameters>((acc, param) => {
+			// @ts-expect-error Silence ts errors
+			switch (param.type?.name) {
+				case 'Unpack':
+					// @ts-expect-error Silence ts errors
+					// eslint-disable-next-line
+					acc.push(...reflections[param.type.typeArguments[0].target].children.map(x => ({...x, flags: {'keyword-only': true}})));
+					break;
+				default:
+					acc.push(param);
+					break;
+			}
+	
+			return acc;
+		}, []);
+		
+		// eslint-disable-next-line
+		sig.parameters = sig.parameters?.reduce<typeof sig.parameters>((acc, param) => {
+			// @ts-expect-error Silence ts errors
+			switch (param.type?.name) {
+				case 'NotRequired':
+					// @ts-expect-error Silence ts errors
+					// eslint-disable-next-line
+					acc.push({...param, type: param.type.typeArguments[0]});
+					break;
+				default:
+					acc.push(param);
+					break;
+			}
+	
+			return acc;
+		}, []);
+	}
+
 	return (
 		<>
 			{!hideSources && <MemberSources reflection={sig} />}
@@ -85,21 +129,71 @@ export function MemberSignatureBody({ hideSources, sig }: MemberSignatureBodyPro
 
 					<ul className="tsd-parameters">
 						{sig.parameters?.map((param) => (
-							<li key={param.id}>
-								<h5>
-									{param.flags?.isRest && <span className="tsd-signature-symbol">...</span>}
-									{`${param.name}: `}
-									<Type type={param.type} />
-									<DefaultValue
-										comment={param.comment}
-										type={param.type}
-										value={param.defaultValue}
-									/>
-									<Flags flags={param.flags} />
-								</h5>
-
-								<Comment comment={param.comment} />
-							</li>
+							<Fragment key={param.id}>
+								<li>
+									<h5>
+										<Flags flags={param.flags} />
+										{param.flags?.isRest && <span className="tsd-signature-symbol">...</span>}
+										{`${param.name}: `}
+										<Type type={param.type} />
+										<DefaultValue
+											comment={param.comment}
+											type={param.type}
+											value={param.defaultValue}
+										/>
+									</h5>
+
+									<Comment comment={param.comment} />
+								</li>
+
+								{param.type?.type === 'reflection' && (
+									<ul key={param.type.declaration.id}>
+										{param.type.declaration?.children?.map((reflectionChild) => (
+											<li key={reflectionChild.id}>
+												<h5>
+													<Flags flags={reflectionChild.flags} />
+													{reflectionChild.flags?.isRest && <span className="tsd-signature-symbol">...</span>}
+													{`${reflectionChild.name}: `}
+													<Type type={reflectionChild.type} />
+													<DefaultValue
+														comment={reflectionChild.comment as unknown as JSONOutput.Comment}
+														type={reflectionChild.type}
+														value={reflectionChild.defaultValue}
+													/>
+												</h5>
+
+												<Comment comment={reflectionChild.comment as unknown as JSONOutput.Comment} />
+											</li>
+										))}
+									</ul>
+								)}
+
+								{param.type?.type === 'union' && (
+									((param.type.types.filter(
+										(unionType) => unionType.type === 'reflection')) as unknown as Models.ReflectionType[]).map(
+										(unionReflectionType) => (
+											<ul key={unionReflectionType.declaration.id}>
+												{unionReflectionType.declaration?.children?.map((unionChild) => (
+													<li key={unionChild.id}>
+														<h5>
+															<Flags flags={unionChild.flags} />
+															{unionChild.flags?.isRest && <span className="tsd-signature-symbol">...</span>}
+															{`${unionChild.name}: `}
+															<Type type={unionChild.type} />
+															<DefaultValue
+																comment={unionChild.comment as unknown as JSONOutput.Comment}
+																type={unionChild.type}
+																value={unionChild.defaultValue}
+															/>
+														</h5>
+
+														<Comment comment={unionChild.comment as unknown as JSONOutput.Comment} />
+													</li>
+												))}
+											</ul>
+										))
+								)}
+							</Fragment>
 						))}
 					</ul>
 				</>

package/src/components/MemberSignatureTitle.tsx

@@ -2,7 +2,8 @@
 // https://github.com/TypeStrong/typedoc-default-themes/blob/master/src/default/partials/member.signature.title.hbs
 
 import { Fragment } from 'react';
-import type { TSDSignatureReflection } from '../types';
+import { usePluginData } from '@docusaurus/useGlobalData';
+import type { GlobalData,TSDSignatureReflection } from '../types';
 import { escapeMdx } from '../utils/helpers';
 import { Type } from './Type';
 import { TypeParametersGeneric } from './TypeParametersGeneric';
@@ -14,6 +15,7 @@ export interface MemberSignatureTitleProps {
 }
 
 export function MemberSignatureTitle({ useArrow, hideName, sig }: MemberSignatureTitleProps) {
+	const { isPython } = usePluginData('docusaurus-plugin-typedoc-api') as GlobalData;
 	// add `*` before the first keyword-only parameter
 	const parametersCopy = sig.parameters?.slice() ?? [];
 	const firstKeywordOnlyIndex = parametersCopy.findIndex((param) => Object.keys(param.flags).includes('keyword-only'));
@@ -50,6 +52,17 @@ export function MemberSignatureTitle({ useArrow, hideName, sig }: MemberSignatur
 					<span>
 						{param.flags?.isRest && <span className="tsd-signature-symbol">...</span>}
 						{escapeMdx(param.name)}
+						{
+							!isPython && (
+								<>
+									<span className="tsd-signature-symbol">
+										{(param.flags?.isOptional || 'defaultValue' in param) && '?'}
+										{': '}
+									</span>
+									<Type type={param.type} />
+								</>
+							)
+						}
 					</span>
 				</Fragment>
 			))}

package/src/components/Type.tsx

@@ -4,6 +4,8 @@
 import { Fragment } from 'react';
 import type { JSONOutput } from 'typedoc';
 import Link from '@docusaurus/Link';
+import { type GlobalData } from '@docusaurus/types';
+import { usePluginData } from '@docusaurus/useGlobalData';
 import { useReflectionMap } from '../hooks/useReflectionMap';
 import type { TSDDeclarationReflection } from '../types';
 import { MemberSignatureTitle } from './MemberSignatureTitle';
@@ -40,6 +42,7 @@ export interface TypeProps {
 // eslint-disable-next-line complexity
 export function Type({ needsParens = false, type: base }: TypeProps) {
 	const reflections = useReflectionMap();
+	const { isPython } = usePluginData('docusaurus-plugin-typedoc-api') as GlobalData;
 
 	if (!base) {
 		return null;
@@ -124,6 +127,10 @@ export function Type({ needsParens = false, type: base }: TypeProps) {
 		case 'literal': {
 			const type = base as JSONOutput.LiteralType;
 
+			if (isPython && type.value === null) {
+				return <span className="tsd-signature-type">None</span>;
+			}
+
 			return <span className="tsd-signature-type">{String(type.value)}</span>;
 		}
 
@@ -203,7 +210,9 @@ export function Type({ needsParens = false, type: base }: TypeProps) {
 
 		case 'reference': {
 			const type = base as JSONOutput.ReferenceType;
-			const ref = type.target ? reflections[Number(type.target)] : null;
+			// eslint-disable-next-line
+			const reflectionIdentifier = type.target ?? (type as any).id;
+			const ref = reflectionIdentifier ? reflections[Number(reflectionIdentifier)] : null;
 			const genericClass = ref?.id && !ref.sources ? 'tsd-signature-type-generic' : '';
 
 			return (
@@ -221,14 +230,22 @@ export function Type({ needsParens = false, type: base }: TypeProps) {
 					)}
 					{type.typeArguments && type.typeArguments.length > 0 && (
 						<>
-							<span className="tsd-signature-symbol">&lt;</span>
+							<span className="tsd-signature-symbol">
+								{
+									isPython ? '[' : '<'
+								}
+							</span>
 							{type.typeArguments.map((t, i) => (
 								<Fragment key={t.type + i}>
 									{i > 0 && <span className="tsd-signature-symbol">, </span>}
 									<Type type={t} />
 								</Fragment>
 							))}
-							<span className="tsd-signature-symbol">&gt;</span>
+							<span className="tsd-signature-symbol">
+								{
+									isPython ? ']' : '>'
+								}
+							</span>
 						</>
 					)}
 				</>

package/src/components/styles.css

@@ -6,6 +6,50 @@
 	--tsd-spacing-horizontal: 1rem;
 }
 
+.tsd-api-options {
+	border-left: 1px solid var(--ifm-toc-border-color);
+	font-size: var(--tsd-font-small);
+	padding-left: var(--ifm-toc-padding-horizontal);
+}
+.tsd-api-options > div:first-child {
+	margin: var(--ifm-toc-padding-vertical) var(--ifm-toc-padding-horizontal);
+}
+.tsd-api-options > label {
+	margin: var(--ifm-toc-padding-vertical) var(--ifm-toc-padding-horizontal);
+}
+.tsd-api-options > label > input {
+	margin: 0 5px 0 0;
+	vertical-align: middle;
+}
+.tsd-api-options > label > span {
+	vertical-align: middle;
+}
+.tsd-api-options > div:last-child {
+	border-bottom: 1px solid var(--ifm-toc-border-color);
+	margin-top: 1rem;
+}
+
+.tsd-api-options-mobile {
+	font-size: var(--tsd-font-small);
+}
+.tsd-api-options-mobile > div:first-child {
+	margin: var(--ifm-toc-padding-vertical) var(--ifm-toc-padding-horizontal);
+}
+.tsd-api-options-mobile > label {
+	margin: var(--ifm-toc-padding-vertical) var(--ifm-toc-padding-horizontal);
+}
+.tsd-api-options-mobile > label > input {
+	margin: 0 5px 0 0;
+	vertical-align: middle;
+}
+.tsd-api-options-mobile > label > span {
+	vertical-align: middle;
+}
+.tsd-api-options-mobile > div:last-child {
+	border-bottom: 1px solid var(--ifm-toc-border-color);
+	margin-top: 1rem;
+}
+
 .tsd-panel {
 	border: 1px solid var(--ifm-card-background-color);
 	border-radius: var(--ifm-global-radius);

package/src/index.ts

@@ -13,12 +13,12 @@ import {
 	generateJson,
 	loadPackageJsonAndDocs,
 } from './plugin/data';
-import { generateJsonFromPythonProject } from './plugin/python-generator';
 import { extractSidebar } from './plugin/sidebar';
 import { getVersionedDocsDirPath, readVersionsMetadata } from './plugin/version';
 import type {
 	ApiOptions,
 	DocusaurusPluginTypeDocApiOptions,
+	GlobalData,
 	LoadedContent,
 	PackageEntryConfig,
 	PackageReflectionGroup,
@@ -149,19 +149,12 @@ export default function typedocApiPlugin(
 
 					console.log(`[${prefix}]:`, 'Generating docs...');
 
-					if (options.python) {
-						await generateJsonFromPythonProject({
-							projectRoot,
-							outFile: path.join(outDir, 'api-typedoc.json'),
-						});
-					} else {
-						await generateJson(
-							projectRoot,
-							entryPoints,
-							path.join(outDir, 'api-typedoc.json'),
-							options,
-						);
-					}
+					await generateJson(
+						projectRoot,
+						entryPoints,
+						path.join(outDir, 'api-typedoc.json'),
+						options,
+					);
 
 					console.log(`[${prefix}]:`, 'Persisting packages...');
 
@@ -207,11 +200,6 @@ export default function typedocApiPlugin(
 									fs.mkdirSync(context.generatedFilesDir, { recursive: true });
 								}
 								fs.copyFileSync(options.pathToCurrentVersionTypedocJSON, outFile);
-							} else if (options.python) {
-								await generateJsonFromPythonProject({
-									projectRoot,
-									outFile,
-								});
 							} else {
 								await generateJson(projectRoot, entryPoints, outFile, options);
 							}
@@ -277,6 +265,10 @@ export default function typedocApiPlugin(
 				return;
 			}
 
+			actions.setGlobalData({
+				isPython: !!options.python,
+			} as GlobalData);
+
 			const docs: PropVersionDocs = {};
 
 			// Create an index of versions for quick lookups.

package/src/plugin/data.ts

@@ -1,7 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import * as TypeDoc from 'typedoc';
-import { JSONOutput, ReflectionKind } from 'typedoc';
+import { type InlineTagDisplayPart, type JSONOutput, ReflectionKind } from 'typedoc'
 import ts from 'typescript';
 import { normalizeUrl } from '@docusaurus/utils';
 import type {
@@ -110,7 +110,42 @@ export function createReflectionMap(
 ): TSDDeclarationReflectionMap {
 	const map: TSDDeclarationReflectionMap = {};
 
+	// eslint-disable-next-line complexity
 	items.forEach((item) => {
+		// Add @reference categories to reflection.
+		const referenceCategories: Record<string, { title: string; children: number[] }> = {};
+		for (const tag of item.comment?.blockTags ?? []) {
+			if (tag.tag === '@reference' && tag.content.length >= 2 && tag.content[0].kind === 'text') {
+				const categoryName = tag.content[0].text.trim();
+				const ref = (tag.content as InlineTagDisplayPart[]).find((t) => t.tag === '@link');
+
+				if (ref && typeof ref.target === 'number') {
+					if (!(categoryName in referenceCategories)) {
+						referenceCategories[categoryName] = { title: categoryName, children: [] };
+					}
+
+					if (!referenceCategories[categoryName].children.includes(ref.target)) {
+						referenceCategories[categoryName].children.push(ref.target);
+					}
+				}
+			}
+		}
+
+		// Update categories with reference categories.
+		if (!item.categories) {
+			// eslint-disable-next-line no-param-reassign
+			item.categories = [];
+		}
+		for (const category of Object.values(referenceCategories)) {
+			if (category.children.length > 0) {
+				const index = item.categories.findIndex((c) => c.title === category.title);
+				if (index === -1) {
+					item.categories.push(category);
+				}
+			}
+		}
+
+		// Add item.
 		map[item.id] = item;
 	});
 

package/src/types.ts

@@ -32,7 +32,7 @@ export interface DocusaurusPluginTypeDocApiOptions
 	typedocOptions?: Partial<TypeDocOptions>;
 
 	/**
-	 * Switches the processing mode to Python-specific pipeline.
+	 * Enables the Python-specific rendering patches.
 	 */
 	python: boolean;
 
@@ -45,6 +45,10 @@ export interface DocusaurusPluginTypeDocApiOptions
 	routeBasePath?: string;
 }
 
+export interface GlobalData {
+	isPython: boolean;
+}
+
 // CONFIG
 
 export interface PackageEntryConfig {

package/lib/plugin/python-generator/index.js

@@ -1,23 +0,0 @@
-'use strict';
-
-const zx = require('zx');
-const pydocMarkdown = require('./pydoc-markdown.js');
-const transformDocs = require('./transform-docs.js');
-async function generateJsonFromPythonProject({
-  outFile,
-  projectRoot
-}) {
-  const pydocJson = await pydocMarkdown.parseWithPydocMarkdown({
-    projectRoot
-  });
-  await zx.spinner('Converting the Python JSON AST to a TypeDoc-compliant file...', async () => {
-    await transformDocs.pydocToTypedoc({
-      moduleName: 'python',
-      // TODO: get from project config files or passed options
-      outFile,
-      pydocJson
-    });
-  });
-}
-exports.generateJsonFromPythonProject = generateJsonFromPythonProject;
-//# sourceMappingURL=index.js.map

package/lib/plugin/python-generator/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sources":["../../../src/plugin/python-generator/index.ts"],"sourcesContent":null,"names":["parseWithPydocMarkdown","spinner","pydocToTypedoc"],"mappings":";;;;;;AAGO,eAAe,6BAA6B,CAAC;AACpD,EAAE,OAAO;AACT,EAAE,WAAW;AACb,CAAC,EAAE;AACH,EAAE,MAAM,SAAS,GAAG,MAAMA,oCAAsB,CAAC;AACjD,IAAI,WAAW;AACf,GAAG,CAAC,CAAC;AACL,EAAE,MAAMC,UAAO,CAAC,+DAA+D,EAAE,YAAY;AAC7F,IAAI,MAAMC,4BAAc,CAAC;AACzB,MAAM,UAAU,EAAE,QAAQ;AAC1B;AACA,MAAM,OAAO;AACb,MAAM,SAAS;AACf,KAAK,CAAC,CAAC;AACP,GAAG,CAAC,CAAC;AACL;;;;"}

package/lib/plugin/python-generator/pydoc-markdown.js

@@ -1,72 +0,0 @@
-'use strict';
-
-const fs = require('node:fs');
-const path = require('node:path');
-const zx = require('zx');
-const _interopDefault = e => e && e.__esModule ? e : {
-  default: e
-};
-const path__default = /*#__PURE__*/_interopDefault(path);
-
-/**
- * Generates the pydoc-markdown configuration file
- * @returns The pydoc-markdown configuration file as a string
- */
-function getConfigYml({
-  projectRoot
-}) {
-  return `
-loaders:
-  - type: python
-    search_path: ["${projectRoot}"]
-processors:
-  - type: filter
-    skip_empty_modules: true
-  - type: crossref
-renderer:
-  type: docusaurus
-  docs_base_path: docs
-  relative_output_path: reference
-  relative_sidebar_path: sidebar.json
-  sidebar_top_level_label: null
-`;
-}
-async function parseWithPydocMarkdown({
-  projectRoot
-}) {
-  // Check whether the user has Python and pydoc-markdown installed
-  for (const cmd of ['python', 'pydoc-markdown']) {
-    try {
-      // eslint-disable-next-line no-await-in-loop
-      await zx.spinner(`Checking for ${cmd}...`, () => zx.$`${cmd} --version`);
-    } catch {
-      throw new Error(`Please install ${cmd} to use this plugin with Python projects.`);
-    }
-  }
-  ;
-
-  // Generate the JSON file
-  try {
-    const configYml = getConfigYml({
-      projectRoot
-    });
-    const configPath = path__default.default.join(__dirname, 'pydoc-markdown.temp.yml');
-    fs.writeFileSync(configPath, configYml);
-    let pydoc = null;
-    await zx.spinner('Parsing the Python project into a JSON AST...', async () => {
-      pydoc = await zx.$`pydoc-markdown --quiet --dump ${configPath}`;
-    });
-    fs.rmSync(configPath);
-
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
-    let json = await pydoc.text();
-    json = json.replaceAll(path__default.default.resolve(projectRoot), 'REPO_ROOT_PLACEHOLDER');
-    return json;
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  } catch (error) {
-    // eslint-disable-next-line 
-    throw new Error(`Failed to generate JSON file from Python project:\n\t${error.stderr.split('\n').slice(-2).join('\n')}`);
-  }
-}
-exports.parseWithPydocMarkdown = parseWithPydocMarkdown;
-//# sourceMappingURL=pydoc-markdown.js.map

package/lib/plugin/python-generator/pydoc-markdown.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"pydoc-markdown.js","sources":["../../../src/plugin/python-generator/pydoc-markdown.ts"],"sourcesContent":null,"names":["spinner","$","path","writeFileSync","rmSync"],"mappings":";;;;;;;;;;AAIA;AACA;AACA;AACA;AACA,SAAS,YAAY,CAAC;AACtB,EAAE,WAAW;AACb,CAAC,EAAE;AACH,EAAE,OAAO,CAAC;AACV;AACA;AACA,mBAAmB,EAAE,WAAW,CAAC;AACjC;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,CAAC,CAAC;AACF,CAAC;AACM,eAAe,sBAAsB,CAAC;AAC7C,EAAE,WAAW;AACb,CAAC,EAAE;AACH;AACA,EAAE,KAAK,MAAM,GAAG,IAAI,CAAC,QAAQ,EAAE,gBAAgB,CAAC,EAAE;AAClD,IAAI,IAAI;AACR;AACA,MAAM,MAAMA,UAAO,CAAC,CAAC,aAAa,EAAE,GAAG,CAAC,GAAG,CAAC,EAAE,MAAMC,IAAC,CAAC,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC;AACzE,KAAK,CAAC,MAAM;AACZ,MAAM,MAAM,IAAI,KAAK,CAAC,CAAC,eAAe,EAAE,GAAG,CAAC,yCAAyC,CAAC,CAAC,CAAC;AACxF,KAAK;AACL,GAAG;AACH,EAAE,CAAC;AACH;AACA;AACA,EAAE,IAAI;AACN,IAAI,MAAM,SAAS,GAAG,YAAY,CAAC;AACnC,MAAM,WAAW;AACjB,KAAK,CAAC,CAAC;AACP,IAAI,MAAM,UAAU,GAAGC,qBAAI,CAAC,IAAI,CAAC,SAAS,EAAE,yBAAyB,CAAC,CAAC;AACvE,IAAIC,gBAAa,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;AACzC,IAAI,IAAI,KAAK,GAAG,IAAI,CAAC;AACrB,IAAI,MAAMH,UAAO,CAAC,+CAA+C,EAAE,YAAY;AAC/E,MAAM,KAAK,GAAG,MAAMC,IAAC,CAAC,8BAA8B,EAAE,UAAU,CAAC,CAAC,CAAC;AACnE,KAAK,CAAC,CAAC;AACP,IAAIG,SAAM,CAAC,UAAU,CAAC,CAAC;AACvB;AACA;AACA,IAAI,IAAI,IAAI,GAAG,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC;AAClC,IAAI,IAAI,GAAG,IAAI,CAAC,UAAU,CAACF,qBAAI,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,uBAAuB,CAAC,CAAC;AAC/E,IAAI,OAAO,IAAI,CAAC;AAChB;AACA,GAAG,CAAC,OAAO,KAAK,EAAE;AAClB;AACA,IAAI,MAAM,IAAI,KAAK,CAAC,CAAC,qDAAqD,EAAE,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AAC7H,GAAG;AACH;;;;"}