2012年2月1日水曜日

python:ドキュメント作成ツール pydoc(2)


前回に続いてpydocです。(出力例)


1.使用準備
python2.1以降の標準ツールなので、わざわざインストールしなくても、python本体がインストールしてあれば使用可能です。


私はpydoc.pyを実行するバッチファイルを作成し、そのショートカットのアイコンをデスクトップに置いて、このアイコンにチェックしたいpythonファイルをドラッグ&ドロップして実行しています。
ここではこの方法をご紹介します。


テキストファイルに以下の例のように書いて「pydoc.bat」として保存し、そのショートカットのアイコンをデスクトップに置きます。


@echo off
python.exe C:\Python26\Lib\pydoc.py -w %1
pause


マシンによって「pydoc.py」のあるフォルダが異なりますので、2行目には本当に「pydoc.py」があるパスを書きます。
「%1」はコマンドプロンプトでの第1引数のことで、ショートカットのアイコンにドラッグ&ドロップしたファイルのフルパスがセットされます。
パラメータ「-w」でhtml版の説明書を出力することを指定します。


このようにして作成するドキュメントのファイル名は、ソースの拡張子「.py」を「.html」に変えたファイル名になります。


例)c:\python26\user\keisan.py
→ c:\python26\user\keisan.html


2.使用されるコメント文
pydocは、pythonソース、クラスや関数のヘッダ部分のコメントからhtml版使用手引きを作成します。取り出されるコメントは以下とおりです。


・ソースのヘッダ
 pythonソースで最初の命令後までの全コメント文が出力されます。


・importしているモジュール名


・クラスや関数のヘッダ
class文やdef文の行と、その前後の命令語との間にあるコメント文が使用されます。
命令語と命令語の間のコメントは出力されません。


・インヘリタンス(クラスの継承)をすると継承元クラスの説明も出力されます。


以上です。