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

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

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

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

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

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

   pydoc sys

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

注釈:

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

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

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

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

また、 **pydoc** を使うことでローカルマシンに Web browserから 閲覧可能
なドキュメントを提供するHTTPサーバーを起動することもできます。 **pydoc
-p 1234** とすると、HTTPサーバーをポート1234に起動します。これで、お好
きなWebブラウザを使って "http://localhost:1234/" から ドキュメントを見
ることができます。ポート番号に "0" を指定すると、任意の空きポートが選
択されます。

**pydoc -b** では、サーバとして起動するとともにブラウザも起動し、モジ
ュールインデクスページを開きます。提供されるページには、個別のヘルプペ
ージに飛ぶための *Get* ボタン、全モジュールから概要行に基くキーワード
検索するための *Search* ボタン、と、*Module index*, *Topics* ,
*Keywords* へのそれぞれリンクがついたナビゲーションバーがページの一番
上に付きます。

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