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

.. module:: pydoc
   :synopsis: ドキュメント生成とオンラインヘルプシステム
.. moduleauthor:: Ka-Ping Yee <ping@lfw.org>
.. sectionauthor:: Ka-Ping Yee <ping@lfw.org>


.. versionadded:: 2.1

.. index::
   single: documentation; generation
   single: documentation; online
   single: help; online

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

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

   pydoc sys

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

.. note::

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

.. % (訳者注："pydoc"を直接起動できない場合には、"pydoc.py"を明示的にpythonに与えます。
.. % pydoc.pyは、pythonのディレクトリの下のlibのディレクトリにありますので、
.. % begin{verbatim}
.. % python <pythondir>\lib\pydoc.py sys
.. % end{verbatim}
.. % とします。)

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

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

また、 :program:`pydoc` を使うことでローカルマシンに Web browserから
閲覧可能なドキュメントを提供するHTTPサーバーを起動することもできます。
:program:`pydoc -p 1234` とすると、HTTPサーバーをポート1234に起動します。
これで、お好きなWebブラウザを使って ``http://localhost:1234/`` から
ドキュメントを見ることができます。
:program:`pydoc -g` はサーバーを起動したうえで、検索用に小さい :mod:`Tkinter`
ベースのGUIを表示します。

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

コアモジュールのドキュメントは http://docs.python.org/library/ にあると仮定されています。
これは、ライブラリリファレンスマニュアルを置いている異なるURLかローカルディレクトリを
環境変数 :envvar:`PYTHONDOCS` に設定することでオーバーライドすることができます。

