doxygenとは
doxygenはcやc++, java, pythonなどのソースコードを自動的にドキュメント化してくれるツールです。ソースコード内にdoxygen用の特殊コマンドをコメントとして記入することで，ソースコードをhtmlやpdf形式としてドキュメント化します(pythonの例)。GUIでの利用も可能ですが，今回は勉強のためにCLIから利用しようと思います。
dockerとは
dockerは手軽にアプリケーションごとのLinux仮想環境を構築できるツールです。元々はLinux専用ツールでしたが、最近MacやWindowsのネイティブアプリのBeta版がリリースされたようです。
構築した環境をイメージとして保存することができ、他のユーザも同じ環境でアプリケーションを利用することが可能です。
docker用のイメージはdocker hubで提供されている、他のユーザが事前に構築したイメージを使うことで簡単に目的のアプリケーション環境が利用できます。
要するに、Linuxのアプリケーションを使いたいけど設定とかいろいろ面倒なので、他の人が作ってくれた環境をそのまま仮想環境に持ってくるということです。
やりたいこと
自分が所属している研究室で気軽にdoxygenが利用できるように、dockerからdoxygenを動かしてソースコードのドキュメント化を行います。普段コマンドラインをあまり触らないような人を想定して解説します。
想定環境
ホストとなるマシンの環境はWindowsを想定しています。また、dockerを利用するためにはPCが仮想化支援機能(AMD-V/Intel VT)に対応している必要があります。古いPCでなければ対応していると思います。
動作確認環境
OS: Windows10 home
PC: ThinkPad E540(Intel VTに対応)
dockerのインストール
Windowsでdockerを利用する場合、2つの選択肢があります。
- docker for windows (beta版)
- docker toolbox
docker for windowsは2016年6月現在、beta版であり、利用するためには事前登録を行ってインストールに必要なトークンを獲得する必要があります。また、docker for windowsを利用するためにはWindowsが提供する仮想マシン実行環境Hyper-Vが必要です(Windows8/8.1/10/ Pro/Education/Enterpriseで利用可)。
docker for windowsはWindowsネイティブアプリであり、Virutual Boxなどの仮想マシン導入が不要になります。
自分が利用しているOS(Windows 10 Home)がHyper-Vに非対応だったため、今回はdocker toolboxを利用します。元々dockerはLinux専用ツールのため、Windowsで利用するためには仮想マシンの導入が必要です。なんだか面倒くさそうですが、docker toolboxを利用すると仮想マシン(Virtual Box)の導入も含めて自動でインストールしてくれます。
docker toolboxのインストール
ここからWindows用のdocker toolboxをダウンロードします。
インストールの前に
dockerのような仮想化技術を利用するためには、仮想化支援機能(AMD-VもしくはIntel VT)を有効にする必要があります。この機能を有効にする設定はBIOSから行います。
BIOSへの入り方は利用しているPCによって異なりますが、PCを起動した時に表示されるファンクションキーやEnterキーを押すとBIOS画面を開くことができるはずです。
自分が使用しているThinkPadの場合は次のようにIntel VTを有効にしました。
1. PCを起動してすぐにEnterキーを押し、Startup Interrupt Menuを開く
2. F1キーを押し、BIOS Setup Utilityを開く
3. 矢印キーでSecurityタブに移動し、Virtualizationの項目をEnterキーで選択する
4. Intel(R) Virtualization TechnologyをEnterキーで選択し、Enabledに変更する
5. F10キーで設定を保存してBIOS画面から抜ける
docker toolboxのインストーラ
ダウンロードしたdocker toolboxのインストーラを実行し、インストーラの指示にしたがってインストールを完了させます。
今回は次のようにすべてのコンポーネントをインストールします。
また以下のQiitaの記事によると、VirtualBoxはNDISSドライバでインストールした方が良いそうです。
- Windows10マシンにDocker Toolbox を入れて個人用の開発環境を作る
- Docker Quickstart Terminalのエラー発生(Looks like something went wrong)について
dockerの動作確認
docker toolboxのインストールが完了したら、Docker Quickstart Terminalを実行します。Docker Quickstart TerminalはGit for bash用のターミナルを起動した後に、仮想マシンや環境変数の設定など、dockerを快適に利用するための設定を自動で行ってくれます。
なお、初めてDocker Quickstart Terminalを実行した際には、VirtualBoxのdocker用仮想マシンがdefaultという名前で作成されます。
上の画像のようなdockerロゴが表示されればインストールは無事に完了していると思われます。
doxygenの利用
まずはdocker hubからdoxygenイメージをダウンロードします。
$ docker pull hytssk/doxygen
しばらく放置してダウンロードが完了したらdoxygenが利用可能になります。
Doxyfileの生成
doxygenの設定ファイルであるDoxyfileを生成します。
ドキュメント化したいソースファイルがあるディレクトリに移動してDoxyfileを生成します。
例えばC:\Users\hoge\Documents\My Projectというディレクトリに移動する場合は
$ cd /c/Users/hoge/Documents/My\ Project
で移動できます。移動したら次のコマンドでDoxyfileを生成できます。
$ docker run --rm -v "${PWD}":/src hytssk/doxygen -g
Doxyfileを生成したら、お好みのテキストエディタでDoxyfileを編集します。
ちなみに、カレントディレクトリをWindowsのエクスプローラで開くためには次のようにします。
$ start .
Doxyfileの設定項目については、次のページがわかりやすいです。
Doxyfile(基本的な設定) — Algo13 2016.04.11 ドキュメント
もっと詳しく知りたい場合は公式の説明を読みましょう。
doxygenの動作確認をするのであれば、次の設定項目を変更するのが良いと思います。
- EXTRACT_ALL : NO ⇒ YES
- RECURSIVE : NO ⇒ YES
ドキュメントの生成
Doxyfileの編集が終わったら、設定内容に基いてソースコードのドキュメント化を行います。
ドキュメント化をするためには、ソースコード内にDoxygen用のコメントを付ける必要があります。
コメントの記述方法の詳細は公式を参照してください。
以下はpythonのコードでの例です。
## テスト関数
#
# ここに関数の詳細な説明を記述します。
# @param hoge: 引数の説明を記述します。
# @return 返り値の説明を記述します。
def test(hoge):
ret = hoge * 3
return ret
doxygen用のコメントを記述したら、次のコマンドを実行してドキュメントを生成します。
$ docker run --rm -v "${PWD}":/src hytssk/doxygen Doxyfile
デフォルト設定では、htmlファイルとpdfファイルがドキュメントとして生成されます。
今回はカレントディレクトリに生成されるhtmlファイルをブラウザで開いてみます。
$ start html/index.html
プロジェクトのページがきちんと表示されれば成功です。
エイリアスの設定
ドキュメント生成の度に長いコマンドを入力するのは面倒なのでエイリアスを次のコマンドで作成します。
$ echo "alias doxygen='docker run --rm -v \"\${PWD}\":/src hytssk/doxygen'" >> ~/.bashrc
$ source ~/.bashrc
これで簡単にdoxygenを利用可能になります。
Doxyfileの生成
$ doxygen -g
ドキュメントの生成
$ doxygen Doxyfile
コマンドライン引数のDoxyfileは省略可能で次のようにすることもできます。
$ doxygen
まとめ
これでdoxygenを簡単に使えるような環境が整ったはずです。
普段doxygenを利用する際には、次のような流れになります。
- ソースコードを編集して, doxygen用のコメントを書く
- Docker Quickstart Terminalを起動する
- ソースコードがあるディレクトリに移動する
$ cd /c/Users/hoge/Documents/My\ Project
- Dockerfileを生成する(すでに存在する場合は不要)
$ doxygen -g
- Dockerfileを編集する(すでに設定済みの場合は不要)
- Doxygenコマンドを実行する
$ doxygen
- 生成したドキュメントを確認する
$ start html/index.html
doxygenをどんどん活用して、日頃からコメントをしっかりつける習慣をつけましょう！