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

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


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

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

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

python -m pydoc sys

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

注釈

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

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

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

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

You can also use pydoc to start an HTTP server on the local machine that will serve documentation to visiting web browsers. python -m pydoc -p 1234 will start a HTTP server on port 1234, allowing you to browse the documentation at http://localhost:1234/ in your preferred web browser. Specifying 0 as the port number will select an arbitrary unused port.

python -m pydoc -n <hostname> will start the server listening at the given hostname. By default the hostname is 'localhost' but if you want the server to be reached from other machines, you may want to change the host name that the server responds to. During development this is especially useful if you want to run pydoc from within a container.

python -m pydoc -b will start the server and additionally open a web browser to a module index page. Each served page has a navigation bar at the top where you can Get help on an individual item, Search all modules with a keyword in their synopsis line, and go to the Module index, Topics and Keywords pages.

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() を使うようになりました。

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