題名通りです。
Sphinxっていうドキュメント作成ツールがあって、これがなかなか簡単に作れる、かつ様々なフォーマットの書き出しに対応してるのですごく使いやすい。
Sphinxについて詳しく知りたい方は以下のURLを参照すればいいような気がします。
Pythonって何？という人のためのSphinxインストール入門
しかしSphinxには自動でプロジェクトのMakefileが生成されるので簡単にビルドできるようになっているんですけど、それでもhtmlファイルをrstファイルが変更される度に自動ビルドしてくれたらもっと便利になるのにとか思うのが人の常。
というわけで、前回の記事と絡めて、
OMakeでSphinxを自動継続ビルドしてみようというのが今回の記事の目的です。
まずはOMakeのインストールから
まず、
OMakeっていうのはGNU/BSDのmakeもどきみたいなソフトです。でも「もどき」っていうのは失礼で、従来のmakeとは比べ物にならないほど多くの機能を備えているソフトです。今回使う自動継続ビルドもOMakeの機能の一つです。
OMakeは標準では入っていないため、面倒くさいかもしれませんがOMakeをインストールする必要があります。とはいっても大抵のリポジトリに入っているので、
sudo apt-get install omake
の一行で完了します。Macは持っていないので分からないですが、恐らくportで十分いけるような気がします。
SphinxをOMakeに対応させる
次にSphinxのプロジェクトをOMakeに対応させます。まずプロジェクトの構成は以下のようなものとします。
- Sphinxのビルドコマンドは"sphinx-build"
- ビルドディレクトリは"_build"
- A4用紙を使用する
- ソースファイルはプロジェクトのルートディレクトリ
別にこれと全く同じじゃなくても勝手に変えればいい話なんですが…
それではOMakeのファイルをインストールしてみます。プロジェクトのルートディレクトリに移動してから、
omake --install
でインストール完了です。OMakerootとOMakefileという2つのファイルができたはずです。
ここでのOMakerootは別にいじらなくていいので無視します。それではOMakefileを改造してみます。
まず開くと変なコードが羅列してありますが、すべて削除。Makefileを開くと
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = _build
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
とかいうhtmlを生成するコマンドがずらっと並んでいるので、その流儀に従ってOMakefileに以下を記述。
# OMakefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = _build
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_a4) $(SPHINXOPTS) .
SRCS = $(glob *.rst)
.DEFAULT: $(SRCS)
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
ここで.DEFAULTの依存先にglob関数を用いてすべてのカレントディレクトリ以下のrstファイルを指定してるのがミソ。これで.DEFAULTターゲットの依存先はすべてのrstファイルになったので、このうちのどれかが変更されたら自動的にビルドが開始されるみたいな。
途中の変数を変更したのは、OMakeではその書き方が禁止されているためです。まーそりゃあそうかもしれません(makeの流儀なのかもしれないけど、自分は最初見たときキモいなーって思った)。
これだけでもうすべての手順は終わり。あとはルートディレクトリから継続監視ビルドの-Pオプションをつけて、
omake -P --verbose
を実行すれば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 . _build/html
Running Sphinx v0.6.3
loading translations [ja]... done
loading pickled environment... done
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
no targets are out of date.
- exit . <.DEFAULT>, 0.56 sec, code 0
*** omake: done (0.57 sec, 0/0 scans, 1/1 rules, 0/74 digests)
*** omake: polling for filesystem changes
と監視してくれるのが分かります。あとはてきとーにrstファイルを変更すれば、自動的にOMakeが変更されたことを感知して勝手にビルドしてくれます。いちいち変更する度にmake htmlなどと打たなくてとっても便利。まさに悦楽の境地。
というように、OMakeはこっちが楽できるような仕掛けを大量に用意してくれています。なにかと便利なので覚えると楽かもしれないです。
ついでに
今思うと「継続監視」っていう機能は別にビルド用途だけじゃなく、他のことにも使えるかもしれないです。例えばhtmlファイルを変更したり追加したら差分だけ勝手にアップロードしてくれるとか、グループ作業で他の人の沢山の画像ファイルを別フォルダで縮小しなきゃなんない(しかもそれが頻繁に変更される)場合とか。
グループ作業にありがちな「
どれが変更されてどれが変更されてないのかごっちゃになってわかんねーよ！誰かリスト作ってくれリスト」みたいなのにも威力を発揮しそうな気がします（ていうか今がまさにそんな感じ）。
Wiredの記事から触発されて作ってみた記事。こーゆうグラフって結構実用的な気がします。視覚的にわかりやすい。
