読者です 読者をやめる 読者になる 読者になる

(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 はほぼすべてがコメントという状態になっているので、
すべての内容を消して SphinxMakefile から抽出した内容を保存します。

# 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:デフォルトだとビルド結果ソースファイル群のサブディレクトリに配置されるため、監視の設定がややこしくなります。