前のトピックへ

26. 開発ツール

次のトピックへ

26.2. doctest — 対話モードを使った使用例の内容をテストする

このページ

26.1. pydoc — ドキュメント生成とオンラインヘルプシステム

バージョン 2.1 で追加.

pydoc モジュールは、Pythonモジュールから自動的にドキュメントを生成します。 生成されたドキュメントをテキスト形式でコンソールに表示したり、 Web ブラウザにサーバとして提供したり、HTMLファイルとして保存したりできます。

組み込み関数の help() を使うことで、対話型のインタプリタからオンラインヘルプを起動することができます。 コンソール用のテキスト形式のドキュメントをつくるのにオンラインヘルプでは pydoc を使っています。 pydoc をPythonインタプリタからはなく、オペレーティングシステムのコマンドプロンプトから起動した場合でも、同じテキスト形式のドキュメントを見ることができます。 例えば、以下をshellから実行すると

pydoc sys

sys モジュールのドキュメントを、Unix の man コマンドのような形式で表示させることができます。 pydoc の引数として与えることができるのは、関数名・モジュール名・パッケージ名、 また、モジュールやパッケージ内のモジュールに含まれるクラス・メソッド・関数へのドット”.”形式での参照です。 pydoc への引数がパスと解釈されるような場合で(オペレーティングシステムのパス区切り記号を含む場合です。 例えばUnixならば “/”(スラッシュ)含む場合になります)、さらに、そのパスがPythonのソースファイルを指しているなら、そのファイルに対するドキュメントが生成されます。

ノート

オブジェクトとそのドキュメントを探すために、 pydoc はドキュメント対象のモジュールを import します。そのため、モジュールレベルのコードはそのときに実行されます。 if __name__ == '__main__': ガードを使って、ファイルがスクリプトとして実行したときのみコードを実行し、importされたときには実行されないようにして下さい。

引数の前に -w フラグを指定すると、コンソールにテキストを表示させるかわりにカレントディレクトリにHTMLドキュメントを生成します。

引数の前に -k フラグを指定すると、引数をキーワードとして利用可能な全てのモジュールの概要を検索します。 検索のやりかたは、Unixの man コマンドと同様です。モジュールの概要というのは、モジュールのドキュメントの一行目のことです。

また、 pydoc を使うことでローカルマシンに Web browserから 閲覧可能なドキュメントを提供するHTTPサーバーを起動することもできます。 pydoc -p 1234`とすると、HTTPサーバーをポート1234に起動します。これで、お好きなWeb browserを使って ``http://localhost:1234/` からドキュメントを見ることができます。

pydoc でドキュメントを生成する場合、その時点での環境とパス情報に基づいてモジュールがどこにあるのか決定されます。 そのため、 pydoc spam を実行した場合につくられる ドキュメントは、Pythonインタプリタを起動して import spam と入力したときに読み込まれるモジュールに対するドキュメントになります。

コアモジュールのドキュメントは http://docs.python.org/library/ にあると仮定されています。 これは、ライブラリリファレンスマニュアルを置いている異なるURLかローカルディレクトリを 環境変数 PYTHONDOCS に設定することでオーバーライドすることができます。