Pythonには標準でソースコードのコメントから簡易的なドキュメント（Help）を作成するコマンド「pydoc」が含まれています。
この「pydoc」を使えばコマンドラインに表示させることも、出力をHTMLファイルにしてJavadocのような感じのファイルを簡単につくることができます。
pydocでドキュメントを作成する方法
pydocを使ってドキュメント生成させるためにはpydocを起動できるようにすることが必要です。
pydocはPythonをインストールしたの「Lib」ディレクトリにある「pydoc.py」を起動します。
ここは通常PATHが設定されていないのでPATHを追加するか簡単に起動できるコマンドファイル（バッチファイル）を作成しておくと良いでしょう。
@python {Pythonをインストールしたフォルダー}/Lib/pydoc.py %*
というコマンドファイル（バッチファイル）を{Pythonをインストールしたフォルダー}に保存すればOKです。
pydocでドキュメントを画面に表示させる
あとは実際にソースファイルにpydocで出力させるためのコメントを埋め込んでおきます。
基本的にはpydocはクラスのクラスやメソッド、関数の最初のコメントをそのままドキュメントに出力してくれます。
以下はサンプルとしてpydocでドキュメントを作成させるために作ったクラスと関数です。
#doc_test.py
def add( param1, param2 ) :
"""
param1とparam2を足す
Args:
param1: int : 数値
param2: int : 数値
Returns:
param1とparam2を足した結果
"""
return param1 + param2
class cal() :
def add( param1, param2 ) :
"""
param1とparam2を足す
Args:
param1: int : 数値
param2: int : 数値
Returns:
param1とparam2を足した結果
"""
return param1 + param2
上記のソースをコマンドラインで
pydoc doc_test
と入力してみます。
※pydocを実行する際は拡張子「.py」は不要です。
実行結果は
Help on module doc_test:
NAME
doc_test
CLASSES
builtins.object
cal
class cal(builtins.object)
| Methods defined here:
|
| add(param1, param2)
| param1とparam2を足す
| Args:
| param1: int : 数値
| param2: int : 数値
| Returns:
| param1とparam2を足した結果
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables (if defined)
|
| __weakref__
| list of weak references to the object (if defined)
FUNCTIONS
add(param1, param2)
param1とparam2を足す
Args:
param1: int : 数値
param2: int : 数値
Returns:
param1とparam2を足した結果
FILE
c:python_testdoc_test.py
とコマンドラインに表示されました。
pydocでドキュメントをHTMLに出力する
pydocには画面にドキュメントを表示させるだけでなくHTML形式のファイルに出力することができます。
HTML形式のファイルに出力には「-w」オプションを設定してpydocを起動します。
pydoc -w doc_test
これを実行すると
wrote doc_test.html
と表示されるはずなので、ブラウザーで開いてみると
のような表示がされます。
まとめ
Pythonで作成したソースコードの簡易的なドキュメントを作成するにはpydocを利用すれば簡単に作成することができます。
そのpydocの設定方法と使い方を解説しました。
一度設定しておけばソースコードのコメントが利用できるので手間もなく簡単にドキュメント化できて便利ですね。
以上、pydocでPythonコードのドキュメントを作成する方法でした。
