(5日目) omake を使って Sphinx の自動ビルドを行う
Sphinx & blockdiag アドベントカレンダー 5日目です。
今日も Sphinx の tips についてご紹介したいと思います。
Sphinx で文書を作成する際は rst ファイルを書いて、make コマンドを実行する、という繰り返しを行います。
もし rst ファイルの編集中にどのような表示になるのか確認したい場合であっても、
make ファイルを実行して成果物が生成されるまで待つ必要があります。
ビルド処理は実行してから数秒(から数十秒)かかるため、単に表示を確認したい場合でもワンテンポ待つことになります。
これは Sphinx で文書を作る際、少々取っつきづらいところです。
rst ファイルの読み書きになれてくるとどのような表示になるか予測できるようになるため、
表示確認の回数は少なくなりますが、エラーチェックやリファレンスの確認などのために
ビルドを走らせたくなることがあります。
そこで、今日は omake コマンドを使って Sphinx プロジェクトの自動ビルドを行う方法をご紹介します。
omake はファイルの更新を検知してコマンドを実行するビルドシステムです。
Sphinx プロジェクトの作成
omake でビルドする Sphinx プロジェクトに制限などはないのですが、
omake で変更検知しやすいよう、ビルドディレクトリとソースディレクトリを分けておくことをおすすめします。
具体的には sphinx-quickstart で Sphinx プロジェクトを作成する際に、
"Separate source and build directories (y/N)" という質問に Yes と答えます。
この設問に Yes と答えた場合と No と答えた場合で以下のようにディレクトリ構成が変化します。
# No と答えた場合 (デフォルト) $ find doc -type d doc doc/_templates doc/_build doc/_static # Yes と答えた場合 $ find doc -type d doc doc/build doc/source doc/source/_templates doc/source/_static
Yes と答えておくと、conf.py や rst ファイルなどソースとなるファイル群が source/ ディレクトリ以下にまとまるため、
omake で監視しやすくなります。*1
omake のインストール
Debian では omake はパッケージ化されているので apt 経由でインストールします。
なお、手元の環境では fam パッケージをインストールしないと omake が正しく動作しなかったので、一緒にインストールします。
$ sudo apt-get install omake fam
CentOS5 でも ocaml-omake というパッケージになっているようなので yum コマンドでインストールできそうです(動作未確認)。
$ sudo yum install ocaml-omake
OMakefile の作成
omake で利用するファイルを生成するため、Sphinx プロジェクトのディレクトリに移動し omake --install を実行します。
$ omake --install
*** omake: creating OMakeroot
*** omake: creating OMakefile
*** omake: project files OMakefile and OMakeroot have been installed
*** omake: you should edit these files before continuing
メッセージが表示されたとおり、OMakeroot, OMakefile というファイルが生成されます。
生成された OMakefile はほぼすべてがコメントという状態になっているので、
すべての内容を消して Sphinx の Makefile から抽出した内容を保存します。
# OMakefile for Sphinx documentation
## You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = bin/sphinx-build
PAPER =
BUILDDIR = _build# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_a4) $(SPHINXOPTS) .SRCS = $(find source/ -type=f)
.DEFAULT: $(SRCS)
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
赤くマーキングした箇所(.DEFAULT 節)は Sphinx が生成した Makefile の html ターゲットの部分と同じ内容です。
また、オレンジ色にマーキングした箇所(SRCS 定義)が監視対象のファイルです。
ここでは source/ ディレクトリ以下のすべてのファイルを対象にしています。
omake の実行
それでは早速 omake を実行しましょう。
$ omake -P --verbose *** omake: reading OMakefiles *** omake: finished reading OMakefiles (0.01 sec) - build . <.DEFAULT> + sphinx-build -b html -d build/doctrees -D latex_paper_size=a4 source build/html Making output directory... Running Sphinx v1.1.2 loading translations [ja]... done loading pickled environment... not yet created building [html]: targets for 1 source files that are out of date updating environment: 1 added, 0 changed, 0 removed reading sources... [100%] index looking for now-outdated files... none found pickling environment... done checking consistency... done preparing documents... done writing output... [100%] index writing additional files... genindex search copying static files... done dumping search index... done dumping object inventory... done build succeeded. - exit . <.DEFAULT>, 2.61 sec, code 0 *** omake: done (2.62 sec, 0/0 scans, 1/1 rules, 1/40 digests) *** omake: polling for filesystem changes
omake を実行すると、最初に一度 Sphinx によるビルドが実行されます。
最後に "polling for filesystem changes" というメッセージを表示したまま、待ち状態になります。
それではこの状態で、他の端末を開いて rst ファイルを編集してみましょう。
ウィンドウを二枚開いて操作しているとわかりやすいのですが、エディタで rst ファイルを保存すると
omake が保存を検知してビルドを実行します。
*** omake: file index.rst changed *** omake: rebuilding - build . <.DEFAULT> + sphinx-build -b html -d build/doctrees -D latex_paper_size=a4 source build/html Running Sphinx v1.1.2 loading translations [ja]... done========================================================================================================= ] 00013 / 00014 loading pickled environment... done building [html]: targets for 1 source files that are out of date updating environment: 0 added, 1 changed, 0 removed reading sources... [100%] index looking for now-outdated files... none found pickling environment... done checking consistency... done preparing documents... done writing output... [100%] index writing additional files... genindex search copying static files... done dumping search index... done dumping object inventory... done build succeeded. - exit . <.DEFAULT>, 1.02 sec, code 0 *** omake: done (1.02 sec, 0/0 scans, 2/2 rules, 3/45 digests) *** omake: polling for filesystem changes
これで自動的にビルドしながら編集を行うことができるようになりました。
注意点
omake を利用する場合の重要な注意点として、"omake は追加されたファイルの保存に反応しない" と言うものがあります。
omake は起動時に監視対象のファイルを確定するため、実行後に追加されたファイルは監視されません。
編集中にファイルを追加する必要がでた場合は、追加後に必ず omake を再起動してください。
文書構成の見直しをしている最中などは omake の恩恵にあずかることが難しいようです。
*1:デフォルトだとビルド結果ソースファイル群のサブディレクトリに配置されるため、監視の設定がややこしくなります。
