pydocでPythonコードのドキュメントを作成する方法

Pythonには標準でソースコードのコメントから簡易的なドキュメント(Help)を作成するコマンド「pydoc」が含まれています。

この「pydoc」を使えばコマンドラインに表示させることも、出力をHTMLファイルにしてJavadocのような感じのファイルを簡単につくることができます。

スポンサーリンク

pydocでドキュメントを作成する方法

pydocを使ってドキュメント生成させるためにはpydocを起動できるようにすることが必要です。

pydocはPythonをインストールしたの「Lib」ディレクトリにある「pydoc.py」を起動します。

ここは通常PATHが設定されていないのでPATHを追加するか簡単に起動できるコマンドファイル(バッチファイル)を作成しておくと良いでしょう。

というコマンドファイル(バッチファイル)を{Pythonをインストールしたフォルダー}に保存すればOKです。

pydocでドキュメントを画面に表示させる

あとは実際にソースファイルにpydocで出力させるためのコメントを埋め込んでおきます。

基本的にはpydocはクラスのクラスやメソッド、関数の最初のコメントをそのままドキュメントに出力してくれます。

以下はサンプルとしてpydocでドキュメントを作成させるために作ったクラスと関数です。

上記のソースをコマンドラインで

と入力してみます。
※pydocを実行する際は拡張子「.py」は不要です。

実行結果は

とコマンドラインに表示されました。

pydocでドキュメントをHTMLに出力する

pydocには画面にドキュメントを表示させるだけでなくHTML形式のファイルに出力することができます。

HTML形式のファイルに出力には「-w」オプションを設定してpydocを起動します。

これを実行すると

と表示されるはずなので、ブラウザーで開いてみると

のような表示がされます。

まとめ

Pythonで作成したソースコードの簡易的なドキュメントを作成するにはpydocを利用すれば簡単に作成することができます。
そのpydocの設定方法と使い方を解説しました。

一度設定しておけばソースコードのコメントが利用できるので手間もなく簡単にドキュメント化できて便利ですね。

以上、pydocでPythonコードのドキュメントを作成する方法でした。

タイトルとURLをコピーしました