pdoc を試してみた：Python パッケージ／モジュールの docstring から API ドキュメントを自動生成する
pdoc は，Python で書いたパッケージやモジュールの API ドキュメントを，docstring を読み取ることにより自動的に作成するツールです．この記事では，私がそれを試してみた結果について，備忘録を兼ねてまとめます．
はじめに
作成したパッケージやモジュール（以下，プロジェクト）には，API ドキュメントを書いた方がよいでしょう．誰かに公開するのなら，なおのことです．ほかの言語と同様に，Python の場合にも，このようなドキュメントの作成を支援するツールは，いくつか存在します．
すぐに思いつく例は Sphinx でしょう．このツールは，もともと Python 自体のドキュメント作成を目的として開発されましたが，現在ではそれにとどまらず，様々な分野のドキュメント作成に利用できます．もちろん，Python で書いたプロジェクトの API ドキュメントを作るための機能も充実しています．しかし，ドキュメントの生成に先立ち，あらかじめいくつかの初期設定が必要であるなど，やや煩雑な面もあります．そのため，代替となる手段を探していました．
そのようなときに見つけたのが，pdoc です．これは，Python プロジェクトのソースコードに記述された docstring を読み取り，自動的に API ドキュメントを作成するというものです．初期設定をせずとも，コマンド一つで，ドキュメントを容易に生成できることが売りとなっているようです．以下では，このツールの導入方法と，ごく基本的な使い方について記します．
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 ドキュメントが作成されます．
