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