【Python】Doxygenでドキュメンテーションコメントを書いてドキュメント化

DoxygenでPythonにドキュメンテーションコメントを書いて、効率的にドキュメント化について紹介します。

## 【Doxygenとは】概要とメリット

Doxygen(http://www.doxygen.jp/) とは、専用の記法でコメントを書くことで、自動でドキュメントを作成することができ、GNU General Public Licenseで配布されています。
自作ライブラリを公開している場合は、とても便利です。

メリット
1 多くのファイル形式(HTML、LATEX、Wordなど)でドキュメントを出力できる。
2 多くの言語に対応している(C++,C,Java,Objective-C,Python,IDL (Corba,Microsoft風),Fortran,VHDL,PHP,C#など)。Pythonには専用のPydocがあるが、Doxygenの記法ならマルチで使用できる。
2 ソースコードを解析するので一貫性が保たれる。
3 内包・依存図,継承図,およびコラボレーション図により視覚化することができる。
4 昔からあり、ユーザーも比較的多いため、今後も継続的に利用できる可能性が高い。

## 【使い方】インストール~環境構築まで

① 下記コマンドでインストールします。

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

② 今回は下記のようなプロジェクト(mylib)の場合、その直下にドキュメントを作成するためのディレクトリ(例:docフォルダ)を作成します。

mylib
 + CMakeLists.txt
 + src
 |  + sample.cpp
 |  +   ...
 + include
 |  + sample.h
 |  +   ...
 + doc   <追加 

③ docディレクトリに移動し、doxygenの設定ファイルを作成します。

$ mkdir doc
$ cd doc
$ doxygen -g 

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

場所 パラメータ 説明
035行 PROJECT_NAME = "mylib" プロジェクト名
095行 OUTPUT_LANGUAGE = Japanese
774行 INPUT = ../ doxygenに読み込ませるディレクトリを指定(例の場合はmylib)
805行 RECURSIVE = YES サブディレクトリを管理対象に含めるかどうか(ライブラリなら普通含めるのでYES)

⑤ Doxyfileのあるディレクトリで下記コマンドを実行するとドキュメントが作成されます。

$ doxygen 

## 【使用例】テンプレート

個人的に最低限これくらいの項目を書いておけばいいんじゃないかなと思うものを載せてみた
@exampleや@code~@endcodeを用いて使用例を載せるとより良いドキュメントになると思う


【Python入門】使い方とサンプル集
Pythonとは、統計処理や機械学習、ディープラーニングといった数値計算分野を中心に幅広い用途で利用されている人気なプログラミング言語です。主な特徴として「効率のよい、短くて読みやすいコードを書きやすい」、「ライブラリが豊富なのでサクッと...
Python
西住工房

コメント

タイトルとURLをコピーしました