"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" オプションが追加されました。
