@vx-oss/docs-python 1.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Fuma
+
+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.

package/dist/_virtual/_rolldown/runtime.js

@@ -0,0 +1,13 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+export { __exportAll };

package/dist/badge.js

@@ -0,0 +1,11 @@
+import { cva } from "class-variance-authority";
+//#region src/badge.ts
+const badgeVariants = cva("text-xs font-medium border p-1 rounded-lg not-prose", { variants: { color: {
+	func: "bg-fdpy-func/10 text-fdpy-func border-fdpy-func/50",
+	attribute: "bg-fdpy-attribute/10 text-fdpy-attribute border-fdpy-attribute/50",
+	class: "bg-fdpy-class/10 text-fdpy-class border-fdpy-class/50",
+	module: "bg-fdpy-module/10 text-fdpy-module border-fdpy-module/50",
+	primary: "bg-fd-primary/10 text-fd-primary border-fd-primary/10"
+} } });
+//#endregion
+export { badgeVariants };

package/dist/build.js

@@ -0,0 +1,179 @@
+import { remarkGfm } from "@vx-oss/docs-core/mdx-plugins/remark-gfm";
+import { remark } from "remark";
+//#region src/build.ts
+const parser = remark().use(remarkGfm).use(function() {
+	(this.data().micromarkExtensions ??= []).push({ disable: { null: ["htmlFlow", "htmlText"] } });
+});
+/** One page per module and class, a class page comes before its module. */
+function buildPages(root, groupBy = "module") {
+	const pages = [];
+	/** file path of an object, without extension */
+	function file(path) {
+		if (groupBy === "none") path = path === root.path ? "" : path.slice(root.path.length + 1);
+		return path.replaceAll(".", "/");
+	}
+	function classPage(cls) {
+		return {
+			path: `${file(cls.path)}.mdx`,
+			title: cls.name,
+			kind: "class",
+			build() {
+				const content = describe(cls.description, cls.docstring);
+				if (cls.attributes.length > 0) content.push(heading("Attributes"), attributes(cls.attributes));
+				const functions = Object.values(cls.functions).sort((a, b) => Number(isConstructor(b)) - Number(isConstructor(a)));
+				if (functions.length > 0) content.push(heading("Functions"), ...functions.map(fn));
+				return {
+					type: "root",
+					children: content
+				};
+			}
+		};
+	}
+	function module(mod) {
+		const classes = Object.values(mod.classes).map(classPage);
+		pages.push(...classes);
+		const modules = Object.values(mod.modules).map(module);
+		const dir = file(mod.path);
+		const folder = classes.length > 0 || modules.length > 0;
+		const page = {
+			path: !dir ? "index.mdx" : folder ? `${dir}/index.mdx` : `${dir}.mdx`,
+			title: mod.name,
+			kind: "module",
+			build(href) {
+				const content = describe(mod.description, mod.docstring);
+				if (mod.attributes.length > 0) content.push(attributes(mod.attributes));
+				const tabs = [];
+				const panels = [];
+				function tab(name, children) {
+					tabs.push(name);
+					panels.push(jsx("Tab", { value: name }, children));
+				}
+				if (classes.length > 0) tab("Class", [cards(classes, href)]);
+				const functions = Object.values(mod.functions);
+				if (functions.length > 0) tab("Functions", functions.map(fn));
+				if (modules.length > 0) tab("Modules", [cards(modules, href)]);
+				if (tabs.length > 0) content.push(jsx("Tabs", { items: tabs }, panels));
+				return {
+					type: "root",
+					children: content
+				};
+			}
+		};
+		pages.push(page);
+		return page;
+	}
+	module(root);
+	return pages;
+}
+function cards(targets, href) {
+	return jsx("Cards", {}, targets.map((target) => jsx("Card", {
+		title: target.title,
+		href: href(target)
+	})));
+}
+function fn(func) {
+	const content = describe(func.description, func.docstring);
+	if (func.source.length > 0) content.push(jsx("PySourceCode", {}, [code("python", func.source)]));
+	if (func.parameters.length > 0) content.push(jsx("div", {}, func.parameters.map(parameter)));
+	content.push(jsx("PyFunctionReturn", { type: func.returns.annotation }, func.returns.description ? markdown(func.returns.description) : []));
+	return jsx("PyFunction", {
+		name: func.name,
+		type: func.signature,
+		kind: isConstructor(func) ? "constructor" : null
+	}, content);
+}
+function isConstructor(func) {
+	return func.name === "__init__";
+}
+function parameter(param) {
+	return jsx("PyParameter", {
+		name: param.name,
+		type: param.annotation,
+		value: param.value
+	}, typeof param.description === "string" ? markdown(param.description) : docstring(param.description));
+}
+function attributes(attrs) {
+	return jsx("PyAttributes", {}, attrs.map((attr) => jsx("PyAttribute", {
+		name: attr.name,
+		type: attr.annotation,
+		value: attr.value
+	}, docstring(attr.description))));
+}
+function describe(description, sections) {
+	const content = description ? markdown(description) : [];
+	content.push(...docstring(sections));
+	return content;
+}
+function docstring(sections) {
+	const content = [];
+	for (const section of sections ?? []) if (section.kind === "text") content.push(...markdown(section.value));
+	else if (section.kind === "admonition") content.push(jsx("Callout", {
+		title: section.title,
+		type: section.value.annotation
+	}, markdown(section.value.description)));
+	else if (section.kind === "examples") for (const [kind, value] of section.value) if (kind === "text") content.push(...markdown(value));
+	else content.push(code("python", value));
+	return content;
+}
+function markdown(text) {
+	return parser.parse(text).children;
+}
+function heading(text) {
+	return {
+		type: "heading",
+		depth: 2,
+		children: [{
+			type: "text",
+			value: text
+		}]
+	};
+}
+function code(lang, value) {
+	return {
+		type: "code",
+		lang,
+		value
+	};
+}
+function jsx(name, props, children = []) {
+	const attributes = [];
+	for (const name in props) {
+		const value = props[name];
+		if (value == null) continue;
+		attributes.push({
+			type: "mdxJsxAttribute",
+			name,
+			value: typeof value === "string" ? value : expression(value)
+		});
+	}
+	return {
+		type: "mdxJsxFlowElement",
+		name,
+		attributes,
+		children
+	};
+}
+/** an array of strings as an attribute expression, with the estree the renderer evaluates */
+function expression(value) {
+	const estree = {
+		type: "Program",
+		sourceType: "module",
+		body: [{
+			type: "ExpressionStatement",
+			expression: {
+				type: "ArrayExpression",
+				elements: value.map((item) => ({
+					type: "Literal",
+					value: item
+				}))
+			}
+		}]
+	};
+	return {
+		type: "mdxJsxAttributeValueExpression",
+		value: JSON.stringify(value),
+		data: { estree }
+	};
+}
+//#endregion
+export { buildPages };

package/dist/components/collapsible.js

@@ -0,0 +1,16 @@
+"use client";
+import { cn } from "cnfast";
+import { jsx } from "react/jsx-runtime";
+import { Collapsible } from "@base-ui/react/collapsible";
+//#region src/components/collapsible.tsx
+const Collapsible$1 = Collapsible.Root;
+const CollapsibleTrigger = Collapsible.Trigger;
+function CollapsibleContent({ children, className, ...props }) {
+	return /* @__PURE__ */ jsx(Collapsible.Panel, {
+		...props,
+		className: (s) => cn("overflow-hidden [&[hidden]:not([hidden='until-found'])]:hidden h-(--collapsible-panel-height) transition-[height,opacity] data-starting-style:opacity-0 data-starting-style:h-0 data-ending-style:h-0 data-ending-style:opacity-0", typeof className === "function" ? className(s) : className),
+		children
+	});
+}
+//#endregion
+export { Collapsible$1 as Collapsible, CollapsibleContent, CollapsibleTrigger };

package/dist/components/index.d.ts

@@ -0,0 +1,33 @@
+import { Tab, Tabs } from "@vx-oss/docs-react/components/tabs";
+import { ReactNode } from "react";
+//#region src/components/index.d.ts
+declare function PyFunction(props: {
+  name: string;
+  type: string;
+  kind?: 'func' | 'constructor';
+  children?: ReactNode;
+}): import("react").JSX.Element;
+declare function PyAttributes({ children }: {
+  children?: ReactNode;
+}): import("react").JSX.Element;
+declare function PyAttribute(props: {
+  name: string;
+  type?: string;
+  value?: string;
+  children?: ReactNode;
+}): import("react").JSX.Element;
+declare function PyParameter(props: {
+  name: string;
+  type?: string;
+  value?: string;
+  children?: ReactNode;
+}): import("react").JSX.Element;
+declare function PySourceCode({ children }: {
+  children: ReactNode;
+}): import("react").JSX.Element;
+declare function PyFunctionReturn({ type, children }: {
+  type?: string;
+  children: ReactNode;
+}): import("react").JSX.Element;
+//#endregion
+export { PyAttribute, PyAttributes, PyFunction, PyFunctionReturn, PyParameter, PySourceCode, Tab, Tabs };

package/dist/components/index.js

@@ -0,0 +1,150 @@
+import { __exportAll } from "../_virtual/_rolldown/runtime.js";
+import { badgeVariants } from "../badge.js";
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "./collapsible.js";
+import { cn } from "cnfast";
+import { cva } from "class-variance-authority";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { buttonVariants } from "@vx-oss/docs-react/components/ui/button";
+import { ChevronRight } from "lucide-react";
+import { highlight } from "@vx-oss/docs-core/highlight";
+import { Tab, Tabs } from "@vx-oss/docs-react/components/tabs";
+//#region src/components/index.tsx
+var components_exports = /* @__PURE__ */ __exportAll({
+	PyAttribute: () => PyAttribute,
+	PyAttributes: () => PyAttributes,
+	PyFunction: () => PyFunction,
+	PyFunctionReturn: () => PyFunctionReturn,
+	PyParameter: () => PyParameter,
+	PySourceCode: () => PySourceCode,
+	Tab: () => Tab,
+	Tabs: () => Tabs
+});
+const cardVariants = cva("bg-fd-card rounded-lg text-sm my-6 p-3 border");
+function PyFunction(props) {
+	return /* @__PURE__ */ jsxs("figure", {
+		className: cn(cardVariants()),
+		children: [/* @__PURE__ */ jsxs("div", {
+			className: "flex gap-2 items-center font-mono flex-wrap mb-4",
+			children: [
+				/* @__PURE__ */ jsx("code", {
+					className: cn(badgeVariants({ color: "func" })),
+					children: props.kind ?? "func"
+				}),
+				props.name,
+				/* @__PURE__ */ jsx(InlineCode, {
+					lang: "python",
+					className: "not-prose text-xs text-fd-muted-foreground",
+					code: props.type
+				})
+			]
+		}), /* @__PURE__ */ jsx("div", {
+			className: "text-fd-muted-foreground prose-no-margin",
+			children: props.children
+		})]
+	});
+}
+function PyAttributes({ children }) {
+	return /* @__PURE__ */ jsx("figure", {
+		className: cn(cardVariants(), "p-0 divide-y"),
+		children
+	});
+}
+function PyAttribute(props) {
+	return /* @__PURE__ */ jsxs("div", {
+		className: "p-3",
+		children: [/* @__PURE__ */ jsxs("div", {
+			className: "flex gap-2 items-center flex-wrap font-mono",
+			children: [
+				/* @__PURE__ */ jsx("code", {
+					className: cn(badgeVariants({ color: "attribute" })),
+					children: "attribute"
+				}),
+				props.name,
+				props.type && /* @__PURE__ */ jsx(InlineCode, {
+					lang: "python",
+					className: "not-prose text-fd-muted-foreground text-xs",
+					code: props.type
+				})
+			]
+		}), /* @__PURE__ */ jsxs("div", {
+			className: "text-fd-muted-foreground prose-no-margin mt-2 empty:hidden",
+			children: [props.value && /* @__PURE__ */ jsx(InlineCode, {
+				lang: "python",
+				className: "not-prose text-xs",
+				code: `= ${props.value}`
+			}), props.children]
+		})]
+	});
+}
+function PyParameter(props) {
+	return /* @__PURE__ */ jsxs("div", {
+		"data-parameter": "",
+		className: "bg-fd-secondary rounded-lg text-sm p-3 border shadow-md rounded-none first:rounded-t-lg last:rounded-b-lg",
+		children: [/* @__PURE__ */ jsxs("div", {
+			className: "flex flex-wrap gap-2 items-center font-mono text-fd-foreground",
+			children: [
+				/* @__PURE__ */ jsx("code", {
+					className: cn(badgeVariants({ color: "primary" })),
+					children: "param"
+				}),
+				props.name,
+				props.type && /* @__PURE__ */ jsx(InlineCode, {
+					lang: "python",
+					className: "ms-auto text-fd-muted-foreground not-prose text-xs",
+					code: props.type
+				})
+			]
+		}), /* @__PURE__ */ jsxs("div", {
+			className: "text-fd-muted-foreground prose-no-margin mt-4 empty:hidden",
+			children: [props.value ? /* @__PURE__ */ jsx(InlineCode, {
+				lang: "python",
+				code: `= ${props.value}`,
+				className: "not-prose text-xs"
+			}) : null, props.children]
+		})]
+	});
+}
+function PySourceCode({ children }) {
+	return /* @__PURE__ */ jsxs(Collapsible, {
+		className: "my-6",
+		children: [/* @__PURE__ */ jsxs(CollapsibleTrigger, {
+			className: cn(buttonVariants({
+				color: "secondary",
+				size: "sm",
+				className: "group"
+			})),
+			children: ["Source Code", /* @__PURE__ */ jsx(ChevronRight, { className: "size-3.5 text-fd-muted-foreground group-data-[panel-open]:rotate-90" })]
+		}), /* @__PURE__ */ jsx(CollapsibleContent, {
+			className: "prose-no-margin",
+			children
+		})]
+	});
+}
+function PyFunctionReturn({ type, children }) {
+	return /* @__PURE__ */ jsxs("div", {
+		className: "border bg-fd-secondary rounded-lg p-3 mt-2",
+		children: [/* @__PURE__ */ jsxs("div", {
+			className: "flex flex-wrap gap-2 not-prose",
+			children: [/* @__PURE__ */ jsx("p", {
+				className: "font-medium me-auto",
+				children: "Returns"
+			}), /* @__PURE__ */ jsx(InlineCode, {
+				lang: "python",
+				code: type ?? "None",
+				className: "text-xs"
+			})]
+		}), children]
+	});
+}
+async function InlineCode({ lang, code, ...rest }) {
+	return highlight(code, {
+		lang,
+		components: { pre: (props) => /* @__PURE__ */ jsx("span", {
+			...props,
+			...rest,
+			className: cn(rest.className, props.className)
+		}) }
+	});
+}
+//#endregion
+export { PyAttribute, PyAttributes, PyFunction, PyFunctionReturn, PyParameter, PySourceCode, Tab, Tabs, components_exports };

package/dist/convert.d.ts

@@ -0,0 +1,29 @@
+import { ModuleInterface } from "./generated.js";
+import { PythonGroupBy } from "./source.js";
+//#region src/convert.d.ts
+interface ConvertOptions {
+  /** base URL of the generated pages, used to link classes and modules from their parent module */
+  baseUrl?: string;
+  /**
+   * group generated pages in a directory:
+   *
+   * - `module`: the name of the root module
+   * - `none`: place them at the root of the output directory
+   *
+   * @defaultValue 'module'
+   */
+  groupBy?: PythonGroupBy;
+}
+interface OutputFile {
+  /** relative to the output directory, e.g. `httpx/_client/index.mdx` */
+  path: string;
+  title: string;
+  /** MDX content, without frontmatter */
+  content: string;
+}
+/** Convert a module into MDX files, one per module and class. */
+declare function convert(mod: ModuleInterface, options?: ConvertOptions): OutputFile[];
+/** Write the converted files into your content directory. */
+declare function write(files: OutputFile[], outDir?: string): Promise<void>;
+//#endregion
+export { ConvertOptions, OutputFile, convert, write };

package/dist/convert.js

@@ -0,0 +1,31 @@
+import { buildPages } from "./build.js";
+import * as fs$1 from "node:fs/promises";
+import * as path from "node:path";
+import { mdxToMarkdown } from "mdast-util-mdx";
+import { remarkGfm } from "@vx-oss/docs-core/mdx-plugins/remark-gfm";
+import { remark } from "remark";
+import { getSlugs } from "@vx-oss/docs-core/source";
+//#region src/convert.ts
+const stringifier = remark().use(remarkGfm).use(function() {
+	(this.data().toMarkdownExtensions ??= []).push(mdxToMarkdown());
+});
+/** Convert a module into MDX files, one per module and class. */
+function convert(mod, options = {}) {
+	const { baseUrl = "/" } = options;
+	const href = (target) => "/" + [...baseUrl.split("/"), ...getSlugs(target.path)].filter(Boolean).join("/");
+	return buildPages(mod, options.groupBy).map((page) => ({
+		path: page.path,
+		title: page.title,
+		content: stringifier.stringify(page.build(href))
+	}));
+}
+/** Write the converted files into your content directory. */
+async function write(files, outDir = "./") {
+	await Promise.all(files.map(async (file) => {
+		const filePath = path.resolve(outDir, file.path);
+		await fs$1.mkdir(path.dirname(filePath), { recursive: true });
+		await fs$1.writeFile(filePath, `---\ntitle: ${JSON.stringify(file.title)}\n---\n\n${file.content}`);
+	}));
+}
+//#endregion
+export { convert, write };

package/dist/generated.d.ts

@@ -0,0 +1,83 @@
+//#region src/generated.d.ts
+interface ModuleInterface {
+  name: string;
+  path: string;
+  description: string | null;
+  docstring: DocstringSection[] | null;
+  modules: {
+    [key: string]: ModuleInterface;
+  };
+  attributes: AttributeInterface[];
+  classes: {
+    [key: string]: ClassInterface;
+  };
+  functions: {
+    [key: string]: FunctionInterface;
+  };
+  version?: string;
+}
+interface ClassInterface {
+  name: string;
+  path: string;
+  description: string | null;
+  docstring: DocstringSection[] | null;
+  parameters: ParameterInterface[];
+  attributes: AttributeInterface[];
+  functions: {
+    [key: string]: FunctionInterface;
+  };
+  source: string;
+  inherited_members: {
+    [key: string]: {
+      kind: string;
+      path: string;
+    }[];
+  };
+}
+interface FunctionInterface {
+  name: string;
+  path: string;
+  signature: string;
+  description: string | null;
+  docstring: DocstringSection[];
+  parameters: ParameterInterface[];
+  returns: ReturnInterface;
+  source: string;
+}
+interface AttributeInterface {
+  name: string;
+  annotation: string | null;
+  description: DocstringSection[] | null;
+  value: string | null;
+}
+type DocstringSection = {
+  kind: 'text';
+  value: string;
+} | {
+  kind: 'admonition';
+  value: {
+    annotation: string;
+    description: string;
+  };
+  title: string;
+} | {
+  kind: 'examples';
+  value: [string, string][];
+} | {
+  kind: string;
+  value: any;
+  title?: string;
+};
+interface ParameterInterface {
+  name: string;
+  annotation: string | null;
+  description: string | DocstringSection[] | null;
+  value?: string | null;
+}
+interface ReturnInterface {
+  name: string;
+  annotation: string | null;
+  description: string | null;
+}
+//#endregion
+export type { AttributeInterface, ClassInterface, DocstringSection, FunctionInterface, ModuleInterface, ParameterInterface, ReturnInterface };

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import { AttributeInterface, ClassInterface, DocstringSection, FunctionInterface, ModuleInterface, ParameterInterface, ReturnInterface } from "./generated.js";
+import { PythonRenderer, PythonRendererResult } from "./renderer.js";
+import { PythonConfig, PythonGroupBy, PythonPage, PythonPageKind, PythonSource, SourceOptions, createPython } from "./source.js";
+import { ConvertOptions, OutputFile, convert, write } from "./convert.js";
+export { type AttributeInterface, type ClassInterface, ConvertOptions, type DocstringSection, type FunctionInterface, type ModuleInterface, OutputFile, type ParameterInterface, PythonConfig, PythonGroupBy, PythonPage, PythonPageKind, type PythonRenderer, type PythonRendererResult, PythonSource, type ReturnInterface, SourceOptions, convert, createPython, write };

package/dist/index.js

@@ -0,0 +1,3 @@
+import { convert, write } from "./convert.js";
+import { createPython } from "./source.js";
+export { convert, createPython, write };

package/dist/plugin.js

@@ -0,0 +1,28 @@
+import { badgeVariants } from "./badge.js";
+import { cn } from "cnfast";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+//#region src/plugin.tsx
+/** Adds a `module`/`class` badge to generated pages in the page tree. */
+function pythonPlugin() {
+	return {
+		name: "fumadocs:python",
+		transformPageTree: { file(node, filePath) {
+			if (!filePath || filePath.endsWith("/index.mdx")) return node;
+			const file = this.storage.read(filePath);
+			if (file?.format !== "page") return node;
+			const python = file.data._python;
+			if (!python) return node;
+			node.name = /* @__PURE__ */ jsxs(Fragment, { children: [
+				node.name,
+				" ",
+				/* @__PURE__ */ jsx("span", {
+					className: cn(badgeVariants({ color: python.kind }), "ms-auto py-0 text-nowrap"),
+					children: python.kind
+				})
+			] });
+			return node;
+		} }
+	};
+}
+//#endregion
+export { pythonPlugin };

package/dist/renderer.d.ts

@@ -0,0 +1,24 @@
+import { ReactNode } from "react";
+import { StructuredData } from "@vx-oss/docs-core/mdx-plugins";
+import { TOCItemType } from "@vx-oss/docs-core/toc";
+import "hast";
+import { MDXComponents } from "mdx/types";
+//#region src/renderer.d.ts
+interface PythonRendererResult {
+  toc: TOCItemType[];
+  body: ReactNode;
+}
+/**
+ * Renders a compiled page. The tree only references components by name, so
+ * rendering maps it to JSX without evaluating any JavaScript.
+ */
+interface PythonRenderer {
+  structuredData: StructuredData;
+  /**
+   * Fumadocs UI's default MDX components and `@vx-oss/docs-python/components`
+   * are included, pass your own to override them.
+   */
+  render: (components?: MDXComponents) => Promise<PythonRendererResult>;
+}
+//#endregion
+export { PythonRenderer, PythonRendererResult };