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

ソースコード: Lib/pydoc.py

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

モジュール、クラス、関数、メソッドについての表示されるドキュメンテーションは、オブジェクトの docstring (つまり __doc__ 属性)に基き、またそれのドキュメント可能なメンバが再帰的に続きます。 docstring がない場合、 pydoc は、クラス、関数、メソッドについてはその定義の直前の、モジュールについてはファイル先頭の、ソースファイルのコメント行のブロックから記述を取得しようと試みます(inspect.getcomments() を参照してください)。

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

pydoc sys

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

注釈

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

コンソールへの出力時には、 pydoc は読みやすさのために出力をページ化しようと試みます。環境変数 PAGER がセットされていれば pydoc はその値で設定されたページ化プログラムを使います。

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

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

また、 pydoc を使うことでローカルマシンに Web browserから 閲覧可能なドキュメントを提供するHTTPサーバーを起動することもできます。 pydoc -p 1234 とすると、HTTPサーバーをポート1234に起動します。これで、お好きなWebブラウザを使って http://localhost:1234/ から ドキュメントを見ることができます。ポート番号に 0 を指定すると、任意の空きポートが選択されます。

pydoc -b では、サーバとして起動するとともにブラウザも起動し、モジュールインデクスページを開きます。提供されるページには、個別のヘルプページに飛ぶための Get ボタン、全モジュールから概要行に基くキーワード検索するための Search ボタン、と、Module index, Topics , Keywords へのそれぞれリンクがついたナビゲーションバーがページの一番上に付きます。

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

コアモジュールのドキュメントは https://docs.python.org/X.Y/library/ にあると仮定されています。 X, Y はそれぞれ Python インタプリタのメジャー、マイナーバージョン番号です。環境変数 PYTHONDOCS を設定することでこれをオーバライドすることが出来、ライブラリリファレンスページを含む別の URL やローカルディレクトリを指定出来ます。

バージョン 3.2 で変更: -b オプションが追加されました。

バージョン 3.3 で変更: -g コマンドラインオプションが削除されました。

バージョン 3.4 で変更: pydoc は、callable からシグニチャの情報を得るのに inspect.getfullargspec() ではなく inspect.signature() を使うようになりました。