Python

實驗性功能

Python 文件產生 (docgen) 功能仍處於實驗階段，請謹慎使用。

簡介

fumadocs-python 會根據 Python 套件的原始碼與 docstring 產生文件。透過一個 Python 指令將套件內容收集成 JSON 檔案後，您可以直接將它作為執行階段的內容來源提供，或將其轉換為 MDX 檔案。

每個模組與類別都會產生一個頁面，其中的函式、屬性與參數則由內附的元件負責算繪。

設定

請安裝套件：

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 撰寫樣式，請加入預設集 (preset) ：

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

Dynamic 來源

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複製錨點連結

樣式複製錨點連結

設定來源複製錨點連結

Dynamic 來源複製錨點連結

編譯器複製錨點連結

產生 MDX 檔案複製錨點連結

本頁目錄

簡介

設定

產生 JSON

樣式

設定來源

Dynamic 來源

編譯器

產生 MDX 檔案