OpenBabelやRDKitのAPIドキュメント

　今回はOpenBabelやRDKitなどのフリーツールを利用してプログラミングする際に必須であるAPIドキュメントについてです。

はじめに

　C++に限らず、何か新しいプログラムを作成する際にAPIドキュメントを頻繁に参照します。知名度のあるソフトウェアであれば、ネット検索してすぐに参照することも可能です。しかしながら、必ずしも最新の情報とは限りません。逆に自分が利用したいバージョンが古く、ネットの情報が既に更新されてしまってる場合もあるでしょう。そのような場合に、OpenBabelやRDKitでドキュメントをCMakeとDoxygenを利用して生成します。

　Doxygenとはソースコードに特殊な記法で記述してあるコメント文を解析して、HTML形式のドキュメントを自動生成してくれるツールです。C++だけでなくJavaやPythonなど色々な言語に対応していて、オープンソースのプログラムにはDoxygen形式のコメントが記述されていることが多いです。つまりオープンソースのプログラムの作者としては、ライブラリの使い方はDoxygenのドキュメントを読んで下さいねと言うことです。

　使っているLinuxシステムによっては”Doxygen”がインストールされていない場合があります。この場合は以下のようなコマンド（Ubuntuでインストールする場合）でDoxygenをインストールしてください。

$ sudo apt install doxygen doxygen-doc graphviz doxygen-gui graphviz-doc

OpenBabelの場合

　OpenBabelをCMakeを利用してビルドする際に、ドキュメントのビルドはデフォルトでは省略されます。したがって、CMakeLists.txtを少しだけ編集する必要があります。git cloneしてダウンロードしたopenbabelディレクトリの下にdocというディレクトリがあります。編集すべきCMakeLists.txtは、このdocディレクトリの中にあります。以下にその最初の10行を示します。7行目にあるOPTIONが”OFF”になっているのですが、これを”ON”に書き換えます。

  1 include(GNUInstallDirs)
  2
  3 file(GLOB man_1 *.1)
  4 install(FILES ${man_1} DESTINATION ${CMAKE_INSTALL_MANDIR}/man1)
  5 install(FILES splash.png DESTINATION share/openbabel/${BABEL_VERSION})
  6
  7 OPTION(BUILD_DOCS "Build Open Babel documentation" OFF)
  8 IF(BUILD_DOCS)
  9     find_package(Doxygen)
 10     if(NOT DOXYGEN_EXECUTABLE)

次に”build”ディレクトリを”openbabel”の下に作成して移動します。

$ mkdir build
$ cd build

そして”cmake”コマンドを実行して”make docs”でドキュメントを作成します。

$ cmake ..
$ make docs

上記コマンドを実行すると、openbabel/docの下にAPI/htmlというディレクトリが作成されます。このAPI/htmlディレクトリの下のindex.shtmlをブラウザで開くとAPIドキュメント読むことが出来ます。

RDKitの場合

　RDKitのAPIドキュメント生成はOpenBabelよりも簡単です。
git clone https://github.com/rdkit/rdkitコマンドによりrdkitというディレクトリにソースコードをダウンロードしたとします。このような場合に、以下のような簡単な手順でドキュメント生成できます。

$ cd rdkit/Code
$ doxygen doxygen/doxygen.config

すると、docsというディレクトが作成されてその下にhtml形式のAPIドキュメントが生成されます。これを読む場合はindex.htmlをブラウザで開きます。

おわりに

　とりあえず最新のAPIドキュメントの生成はこれで出来るかと思います。問題はちゃんと読めるかどうかです。英語が理解できるかどうかと言う問題がありますが、それ以上にプログラミング言語のAPIドキュメントは独特です。こればっかりは慣れるしかないのかもしれません。例えば私はPythonの機械学習ライブラリの一つであるscikit-learnのAPIドキュメントを読む機会があるのですが、正直言ってかなり苦手です。C++と違ってPythonは明示的に変数に型付けされていないので、APIドキュメントを読んでも、関数に何をインプットして良いのか分からないことが多いです。Pythonで変数の型を気にしている時点で間違っているのかもしれませんが、なかなか慣れないです。

　プログラミング言語は色々ありますが、出来ることは大体一緒で、if文が無いとかループ制御出来ないとかはあり得ません。結局、新たにプログラミング言語を習得するということは、そのプログラミング言語のAPIドキュメントを読んで、自分なりにその機能をプログラムに組み込めるように成るかどうかだと思います。そういう意味ではscikit-learnのようなPythonのドキュメントを読めるようになったら、私も一人前のPython使いに成れるかもしれません。