はむ吉(のんびり)の練習ノート

主に(競技)プログラミングや言葉について,思いついたことや,試してみたこと,学んだことを,覚え書きを兼ねてまとめます.その際に参考になった,書籍などの紹介も行います.

pdoc を試してみた:Python パッケージ/モジュールの docstring から API ドキュメントを自動生成する

pdoc は,Python で書いたパッケージやモジュールの API ドキュメントを,docstring を読み取ることにより自動的に作成するツールです.この記事では,私がそれを試してみた結果について,備忘録を兼ねてまとめます.

はじめに

作成したパッケージやモジュール(以下,プロジェクト)には,API ドキュメントを書いた方がよいでしょう.誰かに公開するのなら,なおのことです.ほかの言語と同様に,Python の場合にも,このようなドキュメントの作成を支援するツールは,いくつか存在します.

すぐに思いつく例は Sphinx でしょう.このツールは,もともと Python 自体のドキュメント作成を目的として開発されましたが,現在ではそれにとどまらず,様々な分野のドキュメント作成に利用できます.もちろん,Python で書いたプロジェクトの API ドキュメントを作るための機能も充実しています.しかし,ドキュメントの生成に先立ち,あらかじめいくつかの初期設定が必要であるなど,やや煩雑な面もあります.そのため,代替となる手段を探していました.

そのようなときに見つけたのが,pdoc です.これは,Python プロジェクトのソースコードに記述された docstring を読み取り,自動的に API ドキュメントを作成するというものです.初期設定をせずとも,コマンド一つで,ドキュメントを容易に生成できることが売りとなっているようです.以下では,このツールの導入方法と,ごく基本的な使い方について記します.

動作を確認した環境

後述する操作は,次の環境で行いました.ただ,このツールの場合,OS 依存性はあまりないような気もします.

pdoc の導入

Python 3 付属の pip を使用し,pip3 install pdoc を適切な権限のもとで実行します.これにより,pdoc が,それと関連するパッケージやモジュールとともに導入されます.その後,pdoc --version を実行し,正常に pdoc のバージョン番号が出力されるか確認するとよいでしょう.

ドキュメントを作成する

前述のように,pdoc でプロジェクトの API ドキュメントを作成するには,プロジェクトのソースコードに docstring を記述する必要があります.ここでは,説明のため,docstring を施したごく小さなモジュールを作成し,これを用いてドキュメント生成までを説明することにします.

まずは,docstring を含むモジュールの例を以下に示します.pdoc API documentation に記されているように,docstring の書式としては,reStructuredText や Google スタイルなど,多くがサポートされていますが,ここでは Markdown を用いています.また,docstring に英語以外の言語を使用した場合にも動作することを確かめるため,あえて日本語で記述しています.

上記 test4pdoc.py API ドキュメントを HTML 形式で作成する場合, このモジュールがあるディレクトリで pdoc --html test4pdoc とします.なお,すでに HTML ドキュメントが存在し,これを上書きしたい場合には,pdoc --html test4pdoc --force とします.すると,./test/ 配下に,HTML 形式の API ドキュメントが作成されます.

f:id:hamukichi_nbr:20200609222108p:plain
pdoc により作成された API ドキュメント(HTML 形式)のプレビュー.

おわりに

ドキュメントを書くのはおっくうだと感じていましたが,この pdoc を使えば,負担がずいぶん軽減されると感じました.ただ,あくまでもこのツールは API ドキュメントの作成に特化しているようなので,作りたいドキュメントの種類や規模によっては,上述の Sphinx のような汎用的ツールによるべきでしょう.pdoc は拡張性も高いようなので,もう少し詳しく見てみたいと思います.