# Fumadocs (Framework Mode, Next.js): Python
URL: /docs/next/integrations/content/python
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/[framework]/integrations/content/python.mdx

Generate API references from Python packages.

<Callout type="warn" title="Experimental">
Support for Python docgen is still experimental, use it with caution.
</Callout>

## Introduction [#introduction]

`fumadocs-python` documents a Python package from its source code and docstrings. A Python command collects the package into a JSON file, which you can serve directly as a runtime content source, or convert into MDX files.

Every module and class becomes a page, with functions, attributes and parameters rendered by the included components.

## Setup [#setup]

Install the package:

```package-install
fumadocs-python shiki
```

### Generate JSON [#generate-json]

Install the Python command, it collects docs from your Python package:

```bash
pip install ./node_modules/fumadocs-python
```

Generate the JSON file of a package:

```bash
fumapy-generate httpx
```

It writes `httpx.json` into the current directory, pass `--dir` to change it.

Docstring sections like `Parameters:` and `Returns:` are parsed as Google style, pass `--docstring-style numpy` or `--docstring-style sphinx` for other styles. Docstrings outside these styles are rendered as Markdown.

### Styles [#styles]

The components are styled with Tailwind CSS, add the preset:

```css title="Tailwind CSS"
@import 'tailwindcss';
@import 'fumadocs-ui/css/neutral.css';
@import 'fumadocs-ui/css/preset.css';
/* [!code ++] */
@import 'fumadocs-python/preset.css';
```

### Configure Source [#configure-source]

Create a source from the JSON file and pass it to `loader()`:

```ts title="lib/source.ts"
import { loader } from 'fumadocs-core/source';
import { createPython } from 'fumadocs-python';

const python = createPython({
  file: './httpx.json',
  // Pages are grouped in a directory named after the root module, for example `httpx._client.Client` is served at `/docs/httpx/_client/Client`.
  // Set to "none" to place them at the root of the source instead.
  groupBy: 'module',
});

export const source = loader(await python.staticSource(), {
  baseUrl: '/docs',
  // adds a `module` or `class` badge to generated pages
  plugins: [python.loaderPlugin()],
});
```

Then load and render a page:

```tsx title="app/docs/[[...slug]]/page.tsx"
import { source } from '@/lib/source';
import { notFound } from 'next/navigation';
import { DocsBody, DocsPage, DocsTitle } from 'fumadocs-ui/layouts/docs/page';

export default async function Page({ params }: PageProps<'/docs/[[...slug]]'>) {
  const page = source.getPage((await params).slug);
  if (!page) notFound();

  const data = await page.data.load();
  const { body, toc } = await data.render();

  return (
    <DocsPage toc={toc}>
      <DocsTitle>{page.data.title}</DocsTitle>
      <DocsBody>{body}</DocsBody>
    </DocsPage>
  );
}
```

### Dynamic Source [#dynamic-source]

`staticSource()` reads the JSON file once. To pick up a regenerated file without restarting, use `dynamicSource()` with `dynamicLoader()` instead:

```ts title="lib/source.ts"
import { dynamicLoader } from 'fumadocs-core/source';
import { createPython } from 'fumadocs-python';

const python = createPython({
  file: './httpx.json',
});

const pythonLoader = dynamicLoader(python.dynamicSource(), {
  baseUrl: '/docs',
});

export function getSource() {
  return pythonLoader.get();
}
```

The file is read again after `pythonLoader.invalidate()`, and `getSource()` returns the same [content loader](/docs/headless/source-api) instance until then.

### Compiler [#compiler]

Source code and docstring examples are highlighted with [Shiki](https://shiki.style), configure it with `rehypeCodeOptions`. You can also pass remark/rehype plugins:

```ts title="lib/source.ts"
import { createPython } from 'fumadocs-python';
import remarkMath from 'remark-math';
import rehypeKatex from 'rehype-katex';

const python = createPython({
  file: './httpx.json',
  rehypeCodeOptions: {
    themes: {
      light: 'github-light',
      dark: 'github-dark',
    },
  },
  remarkPlugins: [remarkMath],
  rehypePlugins: [rehypeKatex],
});
```

## Generate MDX Files [#generate-mdx-files]

You can convert the JSON into MDX files instead, and keep them next to your other content. Links between modules and classes are written into the files, so `baseUrl` must match where the output directory is served:

```js tab="scripts/generate-docs.mjs"
import { rimraf } from 'rimraf';
import * as Python from 'fumadocs-python';
import * as fs from 'node:fs/promises';

const content = JSON.parse(await fs.readFile('./httpx.json', 'utf-8'));
// clean previous output
await rimraf('content/docs/httpx');

await Python.write(Python.convert(content, { baseUrl: '/docs' }), 'content/docs');
```

```tsx tab="components/mdx.tsx"
import defaultMdxComponents from 'fumadocs-ui/mdx';
import type { MDXComponents } from 'mdx/types';
import * as Python from 'fumadocs-python/components';

const { createPythonComponents, ...PythonComponents } = Python;

export function getMDXComponents(components?: MDXComponents): MDXComponents {
  return {
    ...defaultMdxComponents,
    ...PythonComponents,
    ...components,
  };
}
```