Python

実験的機能

Python の docgen サポートはまだ実験段階です。注意してご使用ください。

はじめに

fumadocs-python は、Python パッケージのソースコードと docstring からドキュメントを生成します。Python コマンドでパッケージの情報を JSON ファイルにまとめ、そのファイルをランタイムのコンテンツソースとして直接提供するか、MDX ファイルに変換して利用できます。

各モジュールとクラスがそれぞれ 1 つのページになり、関数、属性、パラメーターは付属のコンポーネントによってレンダリングされます。

セットアップ

パッケージをインストールします。

npm install fumadocs-python shiki

JSON を生成する

Python コマンドをインストールします。このコマンドで Python パッケージからドキュメントを収集します。

pip install ./node_modules/fumadocs-python

パッケージのJSONファイルを生成します。

fumapy-generate httpx

カレントディレクトリに httpx.json が書き出されます。出力先を変更するには --dir を指定してください。

Parameters: や Returns: などの docstring セクションは Google スタイルとして解析されます。他のスタイルを使う場合は、--docstring-style numpy または --docstring-style sphinx を指定してください。これらのスタイルに当てはまらない docstring は Markdown としてレンダリングされます。

スタイル

コンポーネントは Tailwind CSS でスタイリングされているため、プリセットを追加します。

Tailwind CSS

@import 'tailwindcss';
@import 'fumadocs-ui/css/neutral.css';
@import 'fumadocs-ui/css/preset.css';
@import 'fumadocs-python/preset.css';

ソースの設定

JSON ファイルからソースを作成し、loader() に渡します。

lib/source.ts

import { loader } from 'fumadocs-core/source';
import { createPython } from 'fumadocs-python';

const python = createPython({
  file: './httpx.json',
  // ページはルートモジュール名のディレクトリにまとめられます。たとえば、`httpx._client.Client` は `/docs/httpx/_client/Client` で配信されます。
  // "none" を設定すると、代わりにソースのルートに配置されます。
  groupBy: 'module',
});

export const source = loader(await python.staticSource(), {
  baseUrl: '/docs',
  // 生成されたページに `module` または `class` のバッジを追加します
  plugins: [python.loaderPlugin()],
});

次に、ページを読み込んでレンダリングします。

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

動的ソース

staticSource() は JSON ファイルを一度しか読み込みません。再起動せずに再生成されたファイルを反映させるには、代わりに dynamicSource() と dynamicLoader() を組み合わせて使用してください。

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();
}

ファイルは pythonLoader.invalidate() を呼び出した後に再度読み込まれます。それまでは、getSource() は同じコンテンツローダーのインスタンスを返します。

コンパイラ

ソースコードと docstring のサンプルは Shiki でハイライトされます。設定は rehypeCodeOptions で行います。remark/rehype プラグインを渡すこともできます。

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],
});

MDX ファイルの生成

代わりに JSON を MDX ファイルに変換し、他のコンテンツと並べて配置することもできます。モジュールやクラス間のリンクはファイルに直接書き込まれるため、baseUrl は出力ディレクトリの配信先と一致させる必要があります。

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'));
// 前回の出力を削除
await rimraf('content/docs/httpx');

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

はじめにアンカーリンクをコピー

セットアップアンカーリンクをコピー

JSON を生成するアンカーリンクをコピー

スタイルアンカーリンクをコピー

ソースの設定アンカーリンクをコピー

動的ソースアンカーリンクをコピー

コンパイラアンカーリンクをコピー

MDX ファイルの生成アンカーリンクをコピー

このページの内容

はじめに

セットアップ

JSON を生成する

スタイル

ソースの設定

動的ソース

コンパイラ

MDX ファイルの生成