@apify/docusaurus-plugin-typedoc-api 4.2.4 → 4.2.6

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;
 	});
 
@@ -286,7 +321,7 @@ function modContainsEntryPoint(
 	// They also don't use full paths like "package/src/index.ts" and simply use "index.ts",
 	// so account for those entry points also.
 	if (!relModSourceFile) {
-		const absEntryPoint = path.normalize(path.join(meta.packageRoot, entry.path));
+		const absEntryPoint = path.normalize(path.join(meta.packageRoot ?? '', entry.path ?? ''));
 		const relEntryPointName = path.basename(relEntryPoint);
 		const entryPointInSourceFiles =
 			!!meta.allSourceFiles[absEntryPoint] ||

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;;;;"}