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

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

The pydoc module automatically generates documentation from Python modules. The documentation can be presented as pages of text on the console, served to a web browser, or saved to HTML files.

For modules, classes, functions and methods, the displayed documentation is derived from the docstring (i.e. the __doc__ attribute) of the object, and recursively of its documentable members. If there is no docstring, pydoc tries to obtain a description from the block of comment lines just above the definition of the class, function or method in the source file, or at the top of the module (see inspect.getcomments()).

The built-in function help() invokes the online help system in the interactive interpreter, which uses pydoc to generate its documentation as text on the console. The same text documentation can also be viewed from outside the Python interpreter by running pydoc as a script at the operating system's command prompt. For example, running

python -m pydoc sys

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

注釈

In order to find objects and their documentation, pydoc imports the module(s) to be documented. Therefore, any code on module level will be executed on that occasion. Use an if __name__ == '__main__': guard to only execute code when a file is invoked as a script and not just imported.

When printing output to the console, pydoc attempts to paginate the output for easier reading. If either the MANPAGER or the PAGER environment variable is set, pydoc will use its value as a pagination program. When both are set, MANPAGER is used.

引数の前に -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インタプリタを起動して import spam と入力したときに読み込まれるモジュールに対するドキュメントになります。

Module docs for core modules are assumed to reside in https://docs.python.org/X.Y/library/ where X and Y are the major and minor version numbers of the Python interpreter. This can be overridden by setting the PYTHONDOCS environment variable to a different URL or to a local directory containing the Library Reference Manual pages.

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

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

バージョン 3.4 で変更: pydoc now uses inspect.signature() rather than inspect.getfullargspec() to extract signature information from callables.

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