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.
コンソールへの出力時には、 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インタプリタを起動して 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
オプションが追加されました。