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

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

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

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

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

python-mpydocsys

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

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

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

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

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

python -m pydoc -n <hostname> は、与えられたホスト名で listen するサーバーを起動します。デフォルトではホスト名は 'localhost' ですが、他のマシンからサーバーへ疎通できるようにしたい場合は、サーバーが応答するホスト名を変更したいと思うでしょう。開発作業中に、コンテナ内で pydoc を走らせたい場合は、これは特に便利です。

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

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

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