Python pydocの使い方、書き方とhtml出力の方法

JavaのJavaDocと同様、Pythonにもpydocがあることは知っていたのですが、
使ったことがなかったので、ちょっと調べてみました。

helpでの表示

pythonのインタープリターを起動して、help()を実行すると、モジュールに
記載されたドキュメントが表示できるようになります。

試しに、httplibと入力してみると、こんな感じでモジュールのドキュメントが表示されました。

なんだかかっこいいです。

「q」と入力すると、helpモードを抜けて、インタープリターに戻ります。

書いてみる

記載した内容がどの部分に表示されるのか知りたかったので、
適当にサンプルを書いてみました。


# -*- coding:utf-8 -*-
"""
ファイルの先頭に書いたコメント
"""
__author__ = "作者 <mail@example.com>"
__status__ = "production"
__version__ = "0.0.1"
__date__    = "01 November 2011"
DATA_TEST = '変数'
class Test(object):
    """
    クラスの先頭に書いたコメント
    """
    def test(self):
        """
        メソッドの先頭に書いたコメント
        """
        pass
    
print("hello world")

sample.pyという名前でファイルを保存し、保存したディレクトリへ移動。
help()を実行した後、

help> sample

を実行してみます。

__author__
__version__
__date__

これらが特殊なキーワードとして扱われるようです。

注意点として、helpは一旦対象のモジュールをimportした後に実行されますので、
例えばサンプルのようなソースの書き方だと、printが実行されてしまいます。

これを避けるために、__name__が'__main__'であるかチェックするようにしてやります。


# -*- coding:utf-8 -*-
"""
ファイルの先頭に書いたコメント
"""
__author__ = "作者 <mail@example.com>"
__status__ = "production"
__version__ = "0.0.1"
__date__    = "01 November 2011"
DATA_TEST = '変数'
class Test(object):
    """
    クラスの先頭に書いたコメント
    """
    def test(self):
        """
        メソッドの先頭に書いたコメント
        """
        pass
    
if __name__ == '__main__':
    print("hello world")

pydocコマンドで表示

pydocコマンドを使用すれば、インタープリターを起動せずに、helpと同じ効果が得られます。

$ pydoc sample

htmlファイルに変換

pydocコマンドの引数に「-w」を追加すると、htmlファイルが生成されます。

$ pydoc -w sample
wrote sample.html

こんな感じのよく見かけるhtmlファイルが出力されました。

関連記事

Symfoware