25.1. pydoc — ドキュメント生成とオンラインヘルプシステム¶
バージョン 2.1 で追加.
ソースコード: Lib/pydoc.py
pydoc モジュールは、Pythonモジュールから自動的にドキュメントを生成します。生成されたドキュメントをテキスト形式でコンソールに表示したり、 Web ブラウザにサーバとして提供したり、HTMLファイルとして保存したりできます。
モジュール, クラス, 関数, メソッドについての表示されるドキュメンテーションは、オブジェクトの docstring (つまり、 __doc__ 属性)に基き、また、それのドキュメント可能なメンバが再帰的に続きます。 docstring がない場合、 pydoc は、クラス, 関数, メソッドについてはその定義の直前の、モジュールについてはファイル先頭の、ソースファイルのコメント行のブロックから記述を取得しようと試みます(inspect.getcomments() を参照してください)。
組み込み関数の help() を使うことで、対話型のインタプリタからオンラインヘルプを起動することができます。コンソール用のテキスト形式のドキュメントをつくるのにオンラインヘルプでは pydoc を使っています。 pydoc をPythonインタプリタからはなく、オペレーティングシステムのコマンドプロンプトから起動した場合でも、同じテキスト形式のドキュメントを見ることができます。例えば、以下の実行を
pydoc sys
shellから行うと sys モジュールのドキュメントを、Unix の man コマンドのような形式で表示させることができます。 pydoc の引数として与えることができるのは、関数名・モジュール名・パッケージ名、また、モジュールやパッケージ内のモジュールに含まれるクラス・メソッド・関数へのドット"."形式での参照です。 pydoc への引数がパスと解釈されるような場合で(オペレーティングシステムのパス区切り記号を含む場合です。例えばUnixならば "/"(スラッシュ)含む場合になります)、さらに、そのパスがPythonのソースファイルを指しているなら、そのファイルに対するドキュメントが生成されます。
注釈
オブジェクトとそのドキュメントを探すために、 pydoc はドキュメント対象のモジュールを import します。そのため、モジュールレベルのコードはそのときに実行されます。 if __name__ == '__main__': ガードを使って、ファイルがスクリプトとして実行したときのみコードを実行し、importされたときには実行されないようにして下さい。
コンソールへの出力時には、 pydoc は読みやすさのために出力をページ化しようと試みます。環境変数 PAGER がセットされていれば pydoc はその値で設定されたページ化プログラムを使います。
引数の前に -w フラグを指定すると、コンソールにテキストを表示させるかわりにカレントディレクトリにHTMLドキュメントを生成します。
引数の前に -k フラグを指定すると、引数をキーワードとして利用可能な全てのモジュールの概要を検索します。検索のやりかたは、Unixの man コマンドと同様です。モジュールの概要というのは、モジュールのドキュメントの一行目のことです。
また、 pydoc を使うことでローカルマシンにウェブブラウザから閲覧可能なドキュメントを提供する HTTP サーバーを起動することもできます。 pydoc -p 1234 とすると、HTTP サーバーをポート 1234 で起動します。これで、お好きなウェブブラウザを使って http://localhost:1234/ からドキュメントを見ることができます。 pydoc -g はサーバーを起動したうえで、検索用に小さい Tkinter ベースの GUI を表示します。
pydoc でドキュメントを生成する場合、その時点での環境とパス情報に基づいてモジュールがどこにあるのか決定されます。そのため、 pydoc spam を実行した場合につくられるドキュメントは、 Pythonインタプリタを起動して import spam と入力したときに読み込まれるモジュールに対するドキュメントになります。
コアモジュールのドキュメントは https://docs.python.org/library/ にあると仮定されています。これは、ライブラリリファレンスマニュアルを置いている異なる URL かローカルディレクトリを環境変数 PYTHONDOCS に設定することでオーバーライドすることができます。