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

バージョン 2.1 で追加.

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

======================================================================

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

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

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

   pydoc sys

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

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

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

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

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

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

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

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