PythonとDoxygenを使ったドキュメンテーションの作成

PythonのコードをDoxygenでドキュメント化する方法について説明します。

Doxygenとは

Doxygenは、専用の記法でコメントを書くことで、自動でドキュメントを作成することができます。Pythonには専用のPydocがありますが、Doxygenの記法ならマルチで使用できます。

Doxygenのインストール

Linuxの場合、以下のコマンドでインストールします。

$ sudo apt-get install graphviz
$ sudo apt-get install doxygen

Macの場合、以下のコマンドでインストールします。

$ brew install doxygen
$ brew install graphviz

Doxygenの設定

Doxygenの設定ファイルを作成します。

$ doxygen -g Doxyfile

Doxyfileを開き、設定を変更します。

Pythonコードのドキュメンテーション

PythonのコードをDoxygenでドキュメント化する際には、docstring形式のコメントをDoxygen形式に変換するフィルターを使用します。

## #@brief Calculates left cosets of H in self.
#@details foo
# #@param H (FiniteGroup) subGroup of self
#@return (Set[Set[GroupElement]])
# #@note bar
def leftCosets(self, H: FiniteGroup) -> Set[Set[GroupElement]]:
    cosets = {frozenset(copy.deepcopy(H.elements)),}
    remain = self.elements - H.elements
    while len(remain) > 0:
        #〜中略〜
    return cosets

このフィルタを使用すると、docstring形式がDoxygen形式に変換されてDoxygenに渡されます。

注意事項

Windows環境でこれをそのまま使うと、cp932で動作して日本語が文字化けしてしまいます。Windows環境で使う場合、doxyfilter_python.pyを編集してエンコーディング”utf-8”を指定します。

以上がPythonとDoxygenを使ったドキュメンテーションの作成方法です。この情報が皆さんのPythonプロジェクトに役立つことを願っています。.