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

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

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

pydocでドキュメントを作成する方法
1. pydocでドキュメントを画面に表示させる
2. pydocでドキュメントをHTMLに出力する
まとめ

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コードのドキュメントを作成する方法でした。