Doxygen vs. Sphinx+Breathe

Introduction

ソフトウェアを開発していると，そのソフトのクラスの構成や使い方，概念などが複雑になってくることがある。また，会社など複数人で開発を行っていると，新しく参加する人のためであったり，数年後に忘れた時のために，APIの説明文書（API文書）があるととても役に立つ。

しかし，こうしたAPI文書を作成する労力は無視できない。また以下の点も文書整備の妨げとなるだろう。

• ソフトウェアの更新。
• 文書整備の優先度の低さ。

こうした問題があるため，文書の整備にかける労力はできる限り小さくしたい。これを実現する手段として，文書化ツールの利用がある。API文書の記述方法には，大きく2パターンが存在し，それに合わせて文書化ツールも分類される。

• ソースコード中に記述（例：Doxygen）
• ソースコードとは別に記述（例：Sphinx）

この件については，以下のブログでも詳しい説明がある。

リファレンスマニュアルの記述方法 – ククログ(2011-05-05)

ソースコード中に記述する代表例はDoxygenであり，ソースコードと分離して記述する代表例はSphinxだと思う。

基本的にはソースコード中に記述する方法のほうが，書き漏らしがなく，ソースコードのすぐ近くで説明をかけるので，労力が少ないだろう。つまり，DoxygenのほうがAPI文書の作成には有利だ。しかし，文書の作成能力としては，Sphinxのほうが柔軟性が高いように思っている。Sphinxは世界中のOSSプロジェクトで採用されており，実績がある。また，Linux Kernelの文書でも採用されており，その利便性が気になっていた。

SphinxでどうにかDoxygen（やソースコードに埋め込まれたDoxygen用のコメント）をうまく使えたらいいなと思っていた。DoxygenのマニュアルのUsing the XML outputでSphinxの拡張機能であるBreatheを使うことで，Doxygenの出力XMLをSphinxで使うことができると知った。そこで，API文書の作成にDoxygen単体とSphinx+Breathe (+Doxygen)のどちらがいいか検討してみた。

Comparison

DoxygenもSphinx+Breatheもあまり使ったことがないので，実際にサンプルを自分で作るのは難しい。そこで，Doxygen単体とSphinx+Breatheが実際に使われた事例をみることにした。具体的には以下のプロジェクトを参照した。

Doxygen単体の事例

Eigen（ソース）

Sphinx+Breatheの事例

ITKExamples（ソース）

例えば，以下のサイトで上記プロジェクトについて言及されていた。

• c++ – What are the main differences of Sphinx and Doxygen? – Stack Overflow
• ITK Sphinx Examples Part III: Cross-linking with Doxygen | The Kitware Blog

上記ページで，この他にも，Doxygen単体の事例として，OpenCVも上げられていた。

比較には，最終成果物であるWebページ（HTML）と元ソースを使った。Webページがいくらきれいでも，元ソースに記載された記法が複雑であれば使用するのは難しいからだ。

Result

検討の結果，Doxygenのほうがよいと判断した。理由は大きく以下2点だ。

• Doxygen単体で書かれたEigenの文書の品質が高く，Doxygen単体でも十分。
• Sphinx+Breatheの実績が少なく，メリットに比べ導入の手間が大きい。

Eigenでは，ソースコードとは別にdocディレクトリに説明文書だけを書いた.doxファイルが大量に配置されている。これらの.doxファイルで主に使い方な ど，APIとの関わりの少ないを見出しをつけて書いている。図表やサンプルコードがふんだんに盛り込まれており，非常に品質の高い文書で感動した。ただし，Doxygenコマンドもふんだんに使われており，Doxygenコマンドには存在しない表などはHTMLコードを書いているので，Doxygenに対する習熟が必要となる。

この一方，Sphinx+Breatheの利点は以下2点だろう。

• Doxygenで抽出したライブラリAPIの柔軟な配置
• Sphinxによる柔軟な文書作成

しかし，Eigenのマニュアルをみて，Doxygenで作られたAPI文書の品質についてはあまり問題にならなくなってしまった。また，Doxygenで抽出したAPIの柔軟な配置をうまく活用した文書の作成はノウハウがないので難しい。実際ITKexamplesでのSphinxの利用はいまいちだった。具体的にはソースコードごとに専用の.rstファイルを作り，そこで単にSphinxの指令を入力してAPIを表示させているだけだった。もう少し込み入った使い方ができないならば，Doxygenで表示させるのと同じで，手間だけが余分にかかっている。

そのため，Sphinx導入に際して発生する以下の2点のデメリット以上のメリットが見当たらなくなってしまった。

• reST記法の習熟
• Sphinxの環境構築

また，Breatheには以下で指摘されている通り問題がいくつかあるようだ。

python – Has anyone used Sphinx to document a C++ project? – Stack Overflow

Doxygenを採用すれば，記法や環境構築はDoxygenだけで済む。Sphinx+Breatheを使う場合でも結局Doxygenコメントを使うので，二度手間となってしまう。やはり，Doxygenだけにしたほうがいいだろう。

余談だが，OpenCVも2系までSphinxを使っていた（Breathe拡張はなし）。しかし，3系からDoxygenに移行している。

• OpenCV 3.0 | OpenCV
• Why did OpenCV 3 change its documentation tool from sphinx to doxygen – OpenCV Q&A Forum

やはりメンテナンス性を考えるなら，Doxygenを使ったほうがいいのだろう。