@apify/docusaurus-plugin-typedoc-api 4.2.10 → 4.2.11-0

package/src/plugin/python/docspec-gen/google_docstring_processor.py

@@ -0,0 +1,185 @@
+# -*- coding: utf8 -*-
+# Copyright (c) 2019 Niklas Rosenstein
+# !!! Modified 2024 Jindřich Bär
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to
+# deal in the Software without restriction, including without limitation the
+# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+# sell copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+
+import dataclasses
+import re
+import typing as t
+
+import docspec
+
+from pydoc_markdown.contrib.processors.sphinx import generate_sections_markdown
+from pydoc_markdown.interfaces import Processor, Resolver
+
+import json
+
+
+@dataclasses.dataclass
+class ApifyGoogleProcessor(Processor):
+    """
+    This class implements the preprocessor for Google and PEP 257 docstrings. It converts
+    docstrings formatted in the Google docstyle to Markdown syntax.
+
+    References:
+
+    * https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html
+    * https://www.python.org/dev/peps/pep-0257/
+
+    Example:
+
+    ```
+    Attributes:
+        module_level_variable1 (int): Module level variables may be documented in
+            either the ``Attributes`` section of the module docstring, or in an
+            inline docstring immediately following the variable.
+
+            Either form is acceptable, but the two should not be mixed. Choose
+            one convention to document module level variables and be consistent
+            with it.
+
+    Todo:
+        * For module TODOs
+        * You have to also use ``sphinx.ext.todo`` extension
+    ```
+
+    Renders as:
+
+    Attributes:
+        module_level_variable1 (int): Module level variables may be documented in
+            either the ``Attributes`` section of the module docstring, or in an
+            inline docstring immediately following the variable.
+
+            Either form is acceptable, but the two should not be mixed. Choose
+            one convention to document module level variables and be consistent
+            with it.
+
+    Todo:
+        * For module TODOs
+        * You have to also use ``sphinx.ext.todo`` extension
+
+    @doc:fmt:google
+    """
+
+    _param_res = [
+        re.compile(r"^(?P<param>\S+):\s+(?P<desc>.+)$"),
+        re.compile(r"^(?P<param>\S+)\s+\((?P<type>[^)]+)\):\s+(?P<desc>.+)$"),
+        re.compile(r"^(?P<param>\S+)\s+--\s+(?P<desc>.+)$"),
+        re.compile(r"^(?P<param>\S+)\s+\{\[(?P<type>\S+)\]\}\s+--\s+(?P<desc>.+)$"),
+        re.compile(r"^(?P<param>\S+)\s+\{(?P<type>\S+)\}\s+--\s+(?P<desc>.+)$"),
+    ]
+
+    _keywords_map = {
+        "Args:": "Arguments",
+        "Arguments:": "Arguments",
+        "Attributes:": "Attributes",
+        "Example:": "Example",
+        "Examples:": "Examples",
+        "Keyword Args:": "Arguments",
+        "Keyword Arguments:": "Arguments",
+        "Methods:": "Methods",
+        "Note:": "Notes",
+        "Notes:": "Notes",
+        "Other Parameters:": "Arguments",
+        "Parameters:": "Arguments",
+        "Return:": "Returns",
+        "Returns:": "Returns",
+        "Raises:": "Raises",
+        "References:": "References",
+        "See Also:": "See Also",
+        "Todo:": "Todo",
+        "Warning:": "Warnings",
+        "Warnings:": "Warnings",
+        "Warns:": "Warns",
+        "Yield:": "Yields",
+        "Yields:": "Yields",
+    }
+
+    def check_docstring_format(self, docstring: str) -> bool:
+        for section_name in self._keywords_map:
+            if section_name in docstring:
+                return True
+        return False
+
+    def process(self, modules: t.List[docspec.Module], resolver: t.Optional[Resolver]) -> None:
+        docspec.visit(modules, self._process)
+
+    def _process(self, node: docspec.ApiObject):
+        if not node.docstring:
+            return
+
+        lines = []
+        sections = []
+        current_lines: t.List[str] = []
+        in_codeblock = False
+        keyword = None
+        multiline_argument_offset = -1
+
+        def _commit():
+            if keyword:
+                sections.append({keyword: list(current_lines)})
+            else:
+                lines.extend(current_lines)
+            current_lines.clear()
+
+        for line in node.docstring.content.split("\n"):
+            multiline_argument_offset += 1
+            if line.lstrip().startswith("```"):
+                in_codeblock = not in_codeblock
+                current_lines.append(line)
+                if not in_codeblock:
+                    _commit()
+                continue
+
+            if in_codeblock:
+                current_lines.append(line)
+                continue
+
+            line = line.strip()
+            if line in self._keywords_map:
+                _commit()
+                keyword = self._keywords_map[line]
+                continue
+
+            if keyword is None:
+                lines.append(line)
+                continue
+
+            for param_re in self._param_res:
+                param_match = param_re.match(line)
+                if param_match:
+                    current_lines.append(param_match.groupdict())
+                    multiline_argument_offset = 0
+                    break
+
+            if not param_match:
+                if multiline_argument_offset == 1:
+                    current_lines[-1]["desc"] += "\n" + line
+                    multiline_argument_offset = 0
+                else:
+                    current_lines.append(line)
+
+        _commit()
+        node.docstring.content = json.dumps({
+            "text": "\n".join(lines),
+            "sections": sections,
+        }, indent=None)
+        
+

package/src/plugin/python/index.ts

@@ -0,0 +1,47 @@
+import childProcess from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import { DocspecTransformer } from './transformation';
+import type { DocspecObject } from './types';
+
+export { groupSort } from './utils';
+
+/**
+ * Processes the Python documentation generated by `pydoc-markdown` and transforms it into a format
+ * accepted by the TypeDoc JSON generator.
+ */
+export function processPythonDocs({
+	pythonModulePath,
+	moduleShortcutsPath,
+	outPath,
+}: {
+	pythonModulePath: string;
+	moduleShortcutsPath: string;
+	outPath: string;
+}) {
+	const pydocMarkdownDumpPath = path.join(__dirname, './pydoc-markdown-dump.json');
+
+	childProcess.spawnSync('python', [
+		path.join(__dirname, './docspec-gen/generate_ast.py'),
+		'-i',
+		pythonModulePath,
+		pydocMarkdownDumpPath,
+	]);
+
+	const moduleShortcuts = JSON.parse(fs.readFileSync(moduleShortcutsPath, 'utf8')) as Record<
+		string,
+		string
+	>;
+
+	const pydocMarkdownDump = JSON.parse(
+		fs.readFileSync(pydocMarkdownDumpPath, 'utf8'),
+	) as DocspecObject[];
+
+	const docspecTransformer = new DocspecTransformer({
+		moduleShortcuts,
+	});
+
+	const typedocApiReference = docspecTransformer.transform(pydocMarkdownDump);
+
+	fs.writeFileSync(outPath, JSON.stringify(typedocApiReference, null, 4));
+}

package/src/plugin/python/inheritance.ts

@@ -0,0 +1,80 @@
+import type { TypeDocObject } from './types';
+import { getGroupName, getOID } from './utils';
+
+/**
+ * Given an ancestor and a descendant objects, injects the children of the ancestor into the descendant.
+ *
+ * Sets the `extendedTypes` / `extendedBy` properties.
+ * @param ancestor
+ * @param descendant
+ */
+export function resolveInheritedSymbols(ancestor: TypeDocObject, descendant: TypeDocObject) {
+	descendant.children ??= [];
+
+	descendant.extendedTypes = [
+		...(descendant.extendedTypes ?? []),
+		{
+			name: ancestor.name,
+			target: ancestor.id,
+			type: 'reference',
+		},
+	];
+
+	ancestor.extendedBy = [
+		...(ancestor.extendedBy ?? []),
+		{
+			name: descendant.name,
+			target: descendant.id,
+			type: 'reference',
+		},
+	];
+
+	for (const inheritedChild of ancestor.children ?? []) {
+		const ownChild = descendant.children?.find((x) => x.name === inheritedChild.name);
+
+		if (!ownChild) {
+			const childId = getOID();
+
+			const { groupName } = getGroupName(inheritedChild);
+			if (!groupName) {
+				throw new Error(
+					`Couldn't resolve the group name for ${inheritedChild.name} (inherited child of ${ancestor.name})`,
+				);
+			}
+
+			const group = descendant.groups?.find((g) => g.title === groupName);
+
+			if (group) {
+				group.children.push(inheritedChild.id);
+			} else {
+				descendant.groups?.push({
+					children: [inheritedChild.id],
+					title: groupName,
+				});
+			}
+
+			descendant.children.push({
+				...inheritedChild,
+				id: childId,
+				inheritedFrom: {
+					name: `${ancestor.name}.${inheritedChild.name}`,
+					target: inheritedChild.id,
+					type: 'reference',
+				},
+			});
+		} else if (!ownChild.comment?.summary?.[0]?.text) {
+			ownChild.inheritedFrom = {
+				name: `${ancestor.name}.${inheritedChild.name}`,
+				target: inheritedChild.id,
+				type: 'reference',
+			};
+
+			for (const key of Object.keys(inheritedChild)) {
+				if (key !== 'id' && key !== 'inheritedFrom') {
+					// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+					ownChild[key as keyof typeof ownChild] = inheritedChild[key as keyof typeof inheritedChild];
+				}
+			}
+		}
+	}
+}

package/src/plugin/python/packageVersions.ts

@@ -0,0 +1,43 @@
+import childProcess from 'child_process';
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Looks for the installed versions of the given packages and returns them as a dictionary.
+ */
+export function getPackageGitHubTags(packageNames: string[]): Record<string, string> {
+	// For each package, get the installed version, and set the tag to the corresponding version
+	const packageTags: Record<string, string> = {};
+
+	for (const pkg of packageNames) {
+		const spawnResult = childProcess.spawnSync('python', [
+			'-c',
+			`import ${pkg}; print(${pkg}.__version__)`,
+		]);
+		if (spawnResult.status === 0) {
+			packageTags[pkg] = `v${spawnResult.stdout.toString().trim()}`;
+		}
+	}
+
+	return packageTags;
+}
+
+export function findNearestInParent(currentPath: string, filename: string) {
+	let parentPath = currentPath;
+	while (parentPath !== '/') {
+		parentPath = path.dirname(parentPath);
+		if (fs.existsSync(path.join(parentPath, filename))) {
+			return path.join(parentPath, filename);
+		}
+	}
+
+	throw new Error(`No ${filename} found in any parent directory`);
+}
+
+export function getCurrentPackageName(pyprojectTomlPath?: string) {
+	const currentPath = path.dirname(__dirname);
+	pyprojectTomlPath ??= findNearestInParent(currentPath, 'pyproject.toml');
+	const pyprojectToml = fs.readFileSync(pyprojectTomlPath, 'utf8');
+
+	return pyprojectToml.match(/^name = "(.+)"$/m)?.[1];
+}