@vx-oss/docs-python 1.0.3

package/dist/renderer.js

@@ -0,0 +1,57 @@
+import { components_exports } from "./components/index.js";
+import * as JsxRuntime from "react/jsx-runtime";
+import { toJsxRuntime } from "hast-util-to-jsx-runtime";
+import defaultMdxComponents from "@vx-oss/docs-react/mdx";
+//#region src/renderer.ts
+function createRenderer(options) {
+	const { tree, structuredData = {
+		headings: [],
+		contents: []
+	}, rehypeToc = [] } = options;
+	return {
+		structuredData,
+		async render(userComponents) {
+			const components = {
+				...defaultMdxComponents,
+				...components_exports,
+				...userComponents
+			};
+			function evaluate(expression) {
+				switch (expression.type) {
+					case "Literal": return expression.value;
+					case "ArrayExpression": return expression.elements.map((item) => item && evaluate(item));
+					case "Identifier":
+						if (expression.name in components) return components[expression.name];
+						throw new Error(`Component "${expression.name}" is missing, pass it to render().`);
+					default: throw new Error(`cannot evaluate ${expression.type} in generated content`);
+				}
+			}
+			const evaluater = {
+				evaluateExpression: evaluate,
+				evaluateProgram() {
+					throw new Error("cannot evaluate programs in generated content");
+				}
+			};
+			function render(tree) {
+				return toJsxRuntime(tree, {
+					components,
+					development: false,
+					createEvaluater: () => evaluater,
+					...JsxRuntime
+				});
+			}
+			return {
+				toc: rehypeToc.map((item) => ({
+					...item,
+					title: render({
+						type: "root",
+						children: item.title.children
+					})
+				})),
+				body: render(tree)
+			};
+		}
+	};
+}
+//#endregion
+export { createRenderer };

package/dist/source.d.ts

@@ -0,0 +1,53 @@
+import { PythonRenderer } from "./renderer.js";
+import { DynamicSource, LoaderPlugin, MetaData, PageData, StaticSource } from "@vx-oss/docs-core/source";
+import { RehypeCodeOptions } from "@vx-oss/docs-core/mdx-plugins/rehype-code";
+import { PluggableList } from "unified";
+import { StructuredData } from "@vx-oss/docs-core/mdx-plugins";
+//#region src/source.d.ts
+interface PythonConfig {
+  /** path to the JSON file generated by `fumapy-generate` */
+  file: string;
+  /**
+   * group generated pages in a directory:
+   *
+   * - `module`: the name of the root module
+   * - `none`: place them at the root of the source
+   *
+   * @defaultValue 'module'
+   */
+  groupBy?: PythonGroupBy;
+  /** additional remark plugins, applied before the structured data is collected */
+  remarkPlugins?: PluggableList;
+  /** additional rehype plugins, applied before the TOC is collected */
+  rehypePlugins?: PluggableList;
+  rehypeCodeOptions?: RehypeCodeOptions | false;
+}
+type PythonPageKind = 'module' | 'class';
+type PythonGroupBy = 'module' | 'none';
+interface PythonPage extends PageData {
+  title: string;
+  /** compile the page, at most once until the source is invalidated */
+  load: () => Promise<PythonRenderer>;
+  structuredData: () => Promise<StructuredData>;
+  _python: {
+    kind: PythonPageKind;
+  };
+}
+interface PythonSource {
+  staticSource: (options?: SourceOptions) => Promise<StaticSource<PythonSourceConfig>>;
+  dynamicSource: (options?: SourceOptions) => DynamicSource<PythonSourceConfig>;
+  /** decorates generated pages in the page tree with a `module`/`class` badge */
+  loaderPlugin: () => LoaderPlugin;
+}
+interface SourceOptions {
+  /** base directory for virtual file paths */
+  baseDir?: string;
+}
+type PythonSourceConfig = {
+  pageData: PythonPage;
+  metaData: MetaData;
+};
+/** Create a runtime Fumadocs content source from the JSON generated by `fumapy-generate`. */
+declare function createPython(config: PythonConfig): PythonSource;
+//#endregion
+export { PythonConfig, PythonGroupBy, PythonPage, PythonPageKind, PythonSource, SourceOptions, createPython };

package/dist/source.js

@@ -0,0 +1,73 @@
+import { buildPages } from "./build.js";
+import { pythonPlugin } from "./plugin.js";
+import { createRenderer } from "./renderer.js";
+import fs from "node:fs/promises";
+import { rehypeCode } from "@vx-oss/docs-core/mdx-plugins/rehype-code";
+import { rehypeToc } from "@vx-oss/docs-core/mdx-plugins/rehype-toc";
+import { remarkHeading } from "@vx-oss/docs-core/mdx-plugins/remark-heading";
+import { remarkStructure } from "@vx-oss/docs-core/mdx-plugins/remark-structure";
+import remarkRehype from "remark-rehype";
+import { unified } from "unified";
+import { VFile } from "vfile";
+//#region src/source.ts
+/** Create a runtime Fumadocs content source from the JSON generated by `fumapy-generate`. */
+function createPython(config) {
+	const processor = unified().use(remarkHeading, { generateToc: false }).use(config.remarkPlugins ?? []).use(remarkStructure).use(remarkRehype, { passThrough: ["mdxJsxFlowElement", "mdxJsxTextElement"] }).use(config.rehypeCodeOptions === false ? [] : [[rehypeCode, {
+		fallbackLanguage: "plaintext",
+		...config.rehypeCodeOptions
+	}]]).use(config.rehypePlugins ?? []).use(rehypeToc, { exportToc: { as: "data" } });
+	async function compile(page, href) {
+		const file = new VFile({ path: page.path });
+		const tree = await processor.run(page.build(href), file);
+		return createRenderer({
+			tree,
+			structuredData: file.data.structuredData,
+			rehypeToc: file.data.rehypeToc
+		});
+	}
+	function createSource({ baseDir } = {}) {
+		let loader;
+		function href(target) {
+			const resolved = loader?.getPageByHref(`./${target.path}`, { dir: baseDir });
+			if (!resolved) throw new Error(`cannot resolve the URL of ${target.path}`);
+			return resolved.page.url;
+		}
+		async function files() {
+			const mod = JSON.parse(await fs.readFile(config.file, "utf-8"));
+			return buildPages(mod, config.groupBy).map((page) => {
+				let loaded;
+				const load = () => loaded ??= compile(page, href);
+				return {
+					type: "page",
+					path: page.path,
+					data: {
+						title: page.title,
+						load,
+						structuredData: async () => (await load()).structuredData,
+						_python: { kind: page.kind }
+					}
+				};
+			});
+		}
+		return {
+			baseDir,
+			files,
+			configureStatic(options) {
+				loader = options.loader;
+			}
+		};
+	}
+	return {
+		dynamicSource: (options) => createSource(options),
+		async staticSource(options) {
+			const { files, ...source } = createSource(options);
+			return {
+				...source,
+				files: await files()
+			};
+		},
+		loaderPlugin: pythonPlugin
+	};
+}
+//#endregion
+export { createPython };

package/fumapy/__init__.py

@@ -0,0 +1,65 @@
+import argparse
+import json
+import os
+
+import griffe
+from griffe_typingdoc import TypingDocExtension
+
+from .mksource import CustomEncoder, parse_module
+
+STORE_SOURCE = True
+
+def generate() -> None:
+    """Generate Python API documentation for a specified module.
+
+    This function parses command-line arguments, loads the specified module,
+    parses its content, and saves the generated API documentation as a JSON file.
+
+    Args:
+        None
+
+    Returns:
+        None
+
+    Raises:
+        argparse.ArgumentTypeError: If invalid arguments are provided.
+        FileNotFoundError: If the specified module or output directory doesn't exist.
+        PermissionError: If there's no write permission for the output directory.
+    """
+    parser = argparse.ArgumentParser(description="Generate python API documentation")
+    parser.add_argument(
+        "module", type=str, help="The module to generate documentation for"
+    )
+    parser.add_argument(
+        "--dir",
+        "-d",
+        type=str,
+        default=".",
+        help="The directory to save the documentation in",
+    )
+    parser.add_argument(
+        "--docstring-style",
+        "-s",
+        choices=["google", "numpy", "sphinx"],
+        default="google",
+        help="The docstring style to parse sections from",
+    )
+    args = parser.parse_args()
+
+    extensions = griffe.load_extensions(TypingDocExtension)
+    pkg = parse_module(
+        griffe.load(
+            args.module,
+            docstring_parser=args.docstring_style,
+            store_source=STORE_SOURCE,
+            extensions=extensions,
+        )
+    )
+    api_filename = f"{args.module}.json"
+
+    with open(os.path.join(args.dir, api_filename), "w") as file:
+        json.dump(pkg, file, cls=CustomEncoder, indent=2, full=True)
+
+
+if __name__ == "__main__":
+    generate()

package/fumapy/mksource/__init__.py

@@ -0,0 +1,10 @@
+from .document_module import parse_class, parse_function, parse_module
+from .json_encoder import CustomEncoder
+
+
+__all__ = (
+    "parse_class",
+    "parse_function",
+    "parse_module",
+    "CustomEncoder",
+)

package/fumapy/mksource/document_module.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+import griffe
+
+from .models import Class, Function, Module
+from .simplify_docstring import simplify_docstring
+from .utils import build_signature
+
+
+def parse_module(m: griffe.Object) -> Module:
+    if not isinstance(m, griffe.Module):
+        raise ValueError("Module must be a module")
+
+    out = simplify_docstring(m.docstring, m)
+    res: Module = {
+        "name": m.name,
+        "path": m.path,
+        "filepath": m.filepath,
+        "description": out.description,
+        "docstring": out.remainder,
+        "attributes": out.attributes,
+        "modules": {
+            name: parse_module(value)
+            for name, value in m.modules.items()
+            if not value.is_alias
+        },
+        "classes": {
+            name: parse_class(value)
+            for name, value in m.classes.items()
+            if not value.is_alias
+        },
+        "functions": {
+            name: parse_function(value)
+            for name, value in m.functions.items()
+            if not value.is_alias
+        },
+    }
+    if m.is_package:
+        try:
+            res["version"] = version(m.name)
+        except PackageNotFoundError:
+            pass
+
+    return res
+
+
+def parse_class(c: griffe.Class) -> Class:
+    out = simplify_docstring(c.docstring, c)
+    res: Class = {
+        "name": c.name,
+        "path": c.path,
+        "description": out.description,
+        "parameters": out.parameters,
+        "attributes": out.attributes,
+        "docstring": out.remainder,
+        "functions": {
+            name: parse_function(value)
+            for name, value in c.functions.items()
+            if not value.is_alias
+        },
+        "source": c.source,
+        "inherited_members": {},
+    }
+    # the class docstring documents the constructor's parameters
+    init = res["functions"].get("__init__")
+    if init is not None:
+        documented = {p["name"]: p["description"] for p in res["parameters"]}
+        for param in init["parameters"]:
+            param["description"] = param["description"] or documented.get(param["name"])
+    for member in c.inherited_members.values():
+        parent_path = ".".join(member.canonical_path.split(".")[:-1])
+        member_info = {"kind": member.kind, "path": member.canonical_path}
+        if parent_path not in res["inherited_members"]:
+            res["inherited_members"][parent_path] = []
+        res["inherited_members"][parent_path].append(member_info)
+    return res
+
+
+def parse_function(f: griffe.Function) -> Function:
+    out = simplify_docstring(f.docstring, f)
+    res: Function = {
+        "name": f.name,
+        "path": f.path,
+        "signature": build_signature(f),
+        "description": out.description,
+        "parameters": out.parameters,
+        "returns": out.returns,
+        "docstring": out.remainder,
+        "source": f.source,
+    }
+    return res

package/fumapy/mksource/json_encoder.py

@@ -0,0 +1,29 @@
+import typing as t
+from pathlib import Path, PosixPath, WindowsPath
+import griffe
+
+_json_encoder_map: dict[type, t.Callable[[t.Any], t.Any]] = {
+    Path: str,
+    PosixPath: str,
+    WindowsPath: str,
+    set: sorted,
+}
+
+
+class CustomEncoder(griffe.JSONEncoder):
+    def default(self, obj: t.Any) -> t.Any:
+        """Return a serializable representation of the given object.
+
+        Parameters:
+            obj: The object to serialize.
+
+        Returns:
+            A serializable representation.
+        """
+
+        try:
+            if isinstance(obj, griffe.Expr):
+                return str(obj)
+            return obj.as_dict(full=self.full)
+        except AttributeError:
+            return _json_encoder_map.get(type(obj), super().default)(obj)

package/fumapy/mksource/models.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import typing as t
+
+
+class Module(t.TypedDict):
+    name: str
+    path: str
+    filepath: str
+    description: str | None
+    docstring: Docstring
+    attributes: list[Attribute]
+    modules: dict[str, Module]
+    classes: dict[str, Class]
+    functions: dict[str, Function]
+    version: str | None
+
+
+class Class(t.TypedDict):
+    name: str
+    path: str
+    description: str | None
+    parameters: list[Parameter]
+    attributes: list[Attribute]
+    docstring: Docstring
+    functions: dict[str, Function]
+    source: str
+
+
+class Function(t.TypedDict):
+    name: str
+    path: str
+    signature: str
+    description: str | None
+    parameters: list[Parameter]
+    returns: dict[str, str | None]
+    docstring: Docstring
+    source: str
+
+
+class DocstringSection(t.TypedDict):
+    kind: str
+    value: str | list[Parameter]
+
+
+Docstring = list[DocstringSection]
+
+
+class Parameter(t.TypedDict):
+    name: str
+    annotation: str
+    description: str
+    value: str
+
+
+class Attribute(t.TypedDict):
+    name: str
+    annotation: str
+    description: str
+    value: str

package/fumapy/mksource/simplify_docstring.py

@@ -0,0 +1,166 @@
+import typing as t
+
+import griffe
+
+from .utils import signature_parameters
+
+
+class SimplifiedDocstring(t.NamedTuple):
+    description: str | None
+    parameters: list[dict[str, str | None]]
+    returns: dict[str, str | None]
+    attributes: list[dict[str, str | None]]
+    remainder: list[griffe.DocstringSection]
+
+
+def simplify_docstring(
+    doc: griffe.Docstring, parent: griffe.Module | griffe.Class | griffe.Function = None
+) -> SimplifiedDocstring:
+    def get_parameters_from_signature(parent: griffe.Class | griffe.Function):
+        return [
+            {
+                "name": p.name,
+                "annotation": p.annotation,
+                "description": None,
+                "value": p.default,
+            }
+            for p in signature_parameters(parent)
+        ]
+
+    def get_returns_from_signature(parent: griffe.Function):
+        return {
+            "name": "",
+            "annotation": (
+                parent.returns
+                if isinstance(parent.returns, (str, type(None)))
+                else "".join(
+                    elem if isinstance(elem, str) else elem.canonical_path
+                    for elem in parent.returns.iterate(flat=True)
+                )
+            ),
+            "description": None,
+        }
+
+    def get_attributes_from_signature(parent: griffe.Module | griffe.Class):
+        return [
+            {
+                "name": attr.name,
+                "annotation": attr.annotation,
+                "description": attr.docstring.parsed if attr.docstring else None,
+                "value": attr.value,
+            }
+            for attr in parent.attributes.values()
+            if (not attr.is_alias and not attr.is_private)
+        ]
+
+    description = None
+    parameters = (
+        get_parameters_from_signature(parent)
+        if isinstance(parent, (griffe.Class, griffe.Function))
+        else None
+    )
+    attributes = (
+        get_attributes_from_signature(parent)
+        if isinstance(parent, (griffe.Class, griffe.Module))
+        else None
+    )
+    returns = (
+        get_returns_from_signature(parent)
+        if isinstance(parent, (griffe.Function))
+        else None
+    )
+    remainder = []
+    if not doc:
+        return SimplifiedDocstring(
+            description, parameters, returns, attributes, remainder
+        )
+
+    for i, sec in enumerate(doc.parsed):
+        if sec.kind == "text" and i == 0:
+            description = sec.value
+            continue
+
+        # Sort the parameters with the real signature
+        if sec.kind == "parameters":
+            map = {i.name: i for i in sec.value}
+            params_list = []
+            for param in signature_parameters(parent):
+                docstring = map.get(param.name)
+                if docstring is None:
+                    params_list.append(
+                        {
+                            "name": param.name,
+                            "annotation": param.annotation,
+                            "description": None,
+                            "value": param.default,
+                        }
+                    )
+                    continue
+
+                try:
+                    documented = griffe.parse_google(griffe.Docstring(docstring.description))
+                except AttributeError:
+                    documented = docstring.description
+                params_list.append(
+                    {
+                        "name": docstring.name,
+                        "annotation": docstring.annotation,
+                        "description": documented,
+                        "value": docstring.value,
+                    }
+                )
+
+            parameters = params_list
+            continue
+
+        if sec.kind == "returns":
+            returns: griffe.DocstringReturn = sec.value[0]
+            returns.annotation = (
+                returns.annotation.canonical_path
+                if isinstance(returns.annotation, griffe.Expr)
+                else returns.annotation
+            )
+            continue
+
+        if sec.kind == "attributes":
+            map = {i.name: i for i in sec.value}
+            attributes_list = []
+            for attr in parent.attributes.values():
+                # exclude aliased attributes
+                if attr.is_alias:
+                    continue
+
+                if attr.name in map:
+                    attr_in_docstring: dict = map[attr.name]
+                    attr_item: dict = {
+                        "name": attr_in_docstring.name,
+                        "description": None,
+                        "annotation": attr_in_docstring.annotation,
+                        "value": attr.value,
+                    }
+
+                    try:
+                        attr_item["description"] = griffe.parse_google(
+                            griffe.Docstring(attr_in_docstring.description)
+                        )
+                    except AttributeError:
+                        pass
+
+                    attributes_list.append(attr_item)
+                else:
+                    attributes_list.append(
+                        {
+                            "name": attr.name,
+                            "annotation": attr.annotation,
+                            "description": (
+                                attr.docstring.parsed if attr.docstring else None
+                            ),
+                            "value": attr.value,
+                        }
+                    )
+            attributes = attributes_list
+            continue
+
+        remainder.append(sec)
+
+    return SimplifiedDocstring(description, parameters, returns, attributes, remainder)

package/fumapy/mksource/utils.py

@@ -0,0 +1,59 @@
+import griffe
+
+
+def signature_parameters(obj: griffe.Class | griffe.Function) -> list[griffe.Parameter]:
+    """Parameters of the signature, without the implicit `self`/`cls` of methods."""
+    parameters = list(obj.parameters)
+    if isinstance(obj, griffe.Class) or (
+        isinstance(obj.parent, griffe.Class) and "staticmethod" not in obj.labels
+    ):
+        return parameters[1:]
+    return parameters
+
+
+def build_signature(func: griffe.Function) -> str:
+    parameters = signature_parameters(func)
+
+    s = "("
+    positional_only = True
+    keyword_only = False
+    for i, p in enumerate(parameters):
+        if i != 0:
+            s += ", "
+        if p.kind in (
+            griffe.ParameterKind.positional_or_keyword,
+            griffe.ParameterKind.keyword_only,
+        ):
+            if positional_only and i != 0:
+                s += "/, "
+            positional_only = False
+
+            if p.kind == griffe.ParameterKind.keyword_only:
+                if not keyword_only:
+                    s += "*, "
+                keyword_only = True
+
+        if p.kind == griffe.ParameterKind.var_keyword:
+            s += f"**{p.name}"
+        elif p.kind == griffe.ParameterKind.var_positional:
+            s += f"*{p.name}"
+        else:
+            s += p.name
+            if p.default is not None:
+                s += f"={p.default}"
+
+    s += ")"
+    if func.returns:
+        s += f" -> {func.returns}"
+
+    return s
+
+
+def filter_non_imported(d: dict[str, griffe.Object]) -> dict:
+    return {k: v for k, v in d.items() if not v.is_imported}
+
+
+def stringify_expr(expr: griffe.Expr | str) -> str:
+    if isinstance(expr, griffe.Expr):
+        return expr.path
+    return expr