Sphinx でドキュメントを書いているとソースファイル (reST) を HTML に変換するために make html コマンドを実行することが多いと思います。しばらく書いてみると、ソースファイルを変更する度にコマンドを実行して HTML を確認するためにブラウザをリロードして ... という操作は煩雑に思えてきます。
Python LiveReload を使うとファイルの変更を検知してブラウザを自動的にリロードできるようになります。設定スクリプトは Python で記述しますので、Python に関するドキュメントを書いている場合は頭の切り替えが要らない点がメリットと言えます。
バージョンによって設定方法が違っており、各種 API も変わっています。バージョン 2.2.1 からはそろそろ Python 3.x でも使えるようになってきましたので、導入方法をまとめておきます。
direnv による環境設定
direnv を使って .envrc と requirements.txt を用意しておくと設定が簡単です。
$ direnv allow .
$ pip install -r requirements.txt
# for Python 2.7
#PYVENV_DIR=$HOME/.pyvenv/sphinx-py27
#PYVENV="virtualenv --distribute"
# for Python 3.4
PYVENV_DIR=$HOME/.pyvenv/sphinx-py34
PYVENV=pyvenv-3.4
[ -d $PYVENV_DIR ] || $PYVENV $PYVENV_DIR
source $PYVENV_DIR/bin/activate
Sphinx
livereload
これで、ターミナルでこのディレクトリに移動すると Sphinx と livereload のパッケージやコマンドを利用できます。
設定ファイル
次に、WSGI アプリケーション用に server.py を用意します。実行ビットを立てておくと起動時のタイプ数が少なくて便利です。
#!/usr/bin/env python
from livereload import Server, shell
server = Server()
server.watch('**/*.rst', shell('make html'))
server.serve(open_url=False)
スクリプトを実行してサーバーを立ち上げます。open_url 引数に True を与えておくと、サーバー起動時にデフォルトのブラウザでページが開きます。
$ ./server.py
あとは普通にドキュメントの reST ソースファイルを編集すると、ファイルを保存したタイミングで make html が実行されてブラウザが更新されます。他にも処理を挟みたい場合は Python で記述できますので、たいがいのことには対応できるでしょう。
おわりに
Python LiveReload を使うと Sphinx でドキュメントを書く作業を快適にできます。Watchdog でも同じようなことを実現できますが、LiveReload はブラウザのリロードまで実行してくれる点が嬉しいですね。
Python 2.x と Python 3.x の両対応で実装が微妙だったり、そもそも対応できていない部分もあるかもしれませんが、ソースファイルを編集する度に手作業でビルドしている場合には導入する価値があると言えるでしょう。
あと、汎用の LiveReload サーバーとしても利用できます。 livereload コマンドでディレクトリを指定した配信ができますので、ちょっとした HTML を編集するにも便利だと思います。