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

バージョン2.1 以降で新規追加された 仕様です。

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

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

    pydoc sys

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

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

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

また、pydocを使うことでローカルマシンに Web browserから 閲覧可能なドキュメントを提供するHTTPサーバーを起動することもできます。 pydoc -p 1234とすると、HTTPサーバーをポート1234に起動します。 これで、お好きなWeb browserを使って`http://localhost:1234/`から ドキュメントを見ることができます。

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