Rustのpyo3アプリケーションからPythonのAPIドキュメントを生成する方法。
|
|
pdoc3は、PythonのドキュメンテーションコメントからMarkDownやHTMLファイルを生成するツール。
pdoc3はPython用のツールであってRust向けのツールではないが、PyO3で作ったアプリケーションでも利用できる。
PyO3を使って定義されたクラスやメソッドに「///」を使ったRustのドキュメンテーションコメントを書いておくと、ビルド後にPythonのドキュメンテーションコメントとして扱われる。
pdoc3はこのPython用ドキュメンテーションコメントを読み込むらしい。
また、Python/Rust混合構成の場合は、__init__.pyに記述したDocstringも使われる。[2026-02-22]
pdoc3は、PyO3を使ったアプリケーションのプロジェクトのPython環境にインストールする。
cd example-pyo3 uv pip install pdoc3 あるいは uv add --dev pdoc3
> uv run pdoc --version pdoc.exe 0.11.6
※インストールするモジュール名はpdoc3だが、インストールされたコマンド名はpdoc。
pdoc3を使ってHTMLを生成する例。
（おそらく、uv run実行時に再ビルドする設定をしておく必要がある）
cd example-pyo3 uv run pdoc example_pyo3 -o docs --html --force
pdocコマンドの引数として、生成対象のPythonモジュール名を指定する。
-oは出力先ディレクトリー。上記の例の場合、「docs/example_pyo3」というディレクトリーが作られ、その下にファイルが生成される。
--htmlはHTMLファイルを生成する指定。
省略するとMarkDownファイルが生成される。（PDFに変換する目的のものらしく、通常のMarkDownとはちょっと違う感じ）
--forceは、既に出力先ディレクトリーが存在している場合に上書きする指定。（これが無いと、既に存在していたらエラーになる）
なお、index.htmlとモジュール名.htmlが生成され、中身はほとんど同一。
どうやら、モジュール名.htmlの方はRustモジュールを表しているようだ。[2026-02-22]
（例えば、example_pyo3はPythonから使うモジュールで、example_pyo3.example_pyo3はRustで生成されたモジュール）
Rustモジュールを不可視にすれば、モジュール名.htmlは生成されなくなる。