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

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

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

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

モジュール、クラス、関数、メソッドのドキュメントは、そのオブジェクトの
docstring (つまり "__doc__" 属性) と、ドキュメント化できるメンバーの
docstring を再帰的にたどって生成されます。 docstring がない場合、
"pydoc" はソースファイル内のクラス、関数、メソッドの定義の直前、または
モジュールの先頭にあるコメント行のブロックから説明を取得しようとします
("inspect.getcomments()" を参照)。

組み込み関数 "help()" は、対話型インタープリタでオンラインヘルプシステ
ムを呼び出します。 このシステムは "pydoc" を使ってドキュメントを生成し
、コンソールにテキストで表示します。 同じテキストドキュメントは、オペ
レーティングシステムのコマンドプロンプトで **pydoc** をスクリプトとし
て実行し、Python インタープリタの外からも表示できます。 例えば、次のコ
マンドを実行します。

   python -m pydoc sys

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

注釈:

  オブジェクトとそのドキュメントを見つけるため、"pydoc" はドキュメント
  化するモジュールをインポートします。 そのため、モジュールレベルのコ
  ードはこのときに実行されます。 単にインポートされたときではなく、フ
  ァイルをスクリプトとして実行したときだけコードを実行するには、"if
  __name__ == '__main__':" で保護してください。

コンソールに出力するとき、**pydoc** は読みやすいように出力をページに分
けようとします。 環境変数 "MANPAGER" または "PAGER" が設定されていれば
、**pydoc** はその値をページ表示プログラムとして使います。 両方が設定
されている場合は "MANPAGER" を使います。

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

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

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

警告:

  "pydoc" の HTTP サーバーは、開発中にローカルで使うことを想定しており
  、本番環境での使用には適していません。

**python -m pydoc -n <hostname>** は、与えられたホスト名で listen する
サーバーを起動します。 デフォルトではホスト名は 'localhost' ですが、他
のマシンからサーバーへ疎通できるようにしたい場合は、サーバーが応答する
ホスト名を変更したいと思うでしょう。 開発作業中に、コンテナ内で pydoc
を走らせたい場合は、これは特に便利です。

**python -m 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" は呼び出し可能オブジェクトからシグネチ
ャ情報を抽出するために、"inspect.getfullargspec()" の代わりに
"inspect.signature()" を使うようになりました。

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