概要
本稿では、Sphinxドキュメントを保存するたびに自動的にビルド、ブラウザをリロードしてくれるツールsphinx-autobuildを紹介し、インストール方法や使い方を簡単に説明します。sphinx-autobuildを使うことで、再ビルド、ブラウザの再リロードの手間を省いて、より楽にSphinx文書を作成できます。
はじめに
最近Sphinxを使い始めました。手軽に文章を体系的にまとめることができ、またバージョン管理もしやすく便利に使っています。
しかし、HTML形式などでできあがったドキュメントを見るには、ビルドコマンドを実行しなければならないのが不便です。ブラウザで閲覧している場合、ページの更新も必要です。
そこで、sphinx-autobuildを導入しました。sphinx-autobuildには下記の機能があり、前述の手間が省けます。
- 自動ビルド機能：ソースディレクトリ内のファイルに変更があると、自動的にビルドを実行する
- 自動リロード機能：ブラウザで閲覧中のページに変更があると、ブラウザを自動的に更新する
reStructuredTextファイルを保存するだけですぐに結果を確認できるため、文書作成がさらに楽になりました。
インストール方法
下記のコマンドでインストールします。Python 2, 3の両方に対応しています。
pip install sphinx-autobuild
2014/12/30時点の最新バージョンである0.4.0は、OS Xを含むUnix系の環境で動作します。Windowsでは、Python 2系との組み合わせでのみ正しく動作します（Python 3系では、sphinx-autobuildが利用しているlivereload 2.3.2の問題のため、自動リロード機能が正しく働きません）。
使い方
下記のコマンドを実行すると、ソースディレクトリ内のファイルの監視が始まります。ファイルが変更されるたびに、自動的にビルドが始まります。
sphinx-autobuild <ソースディレクトリ> <ビルド成果物出力ディレクトリ>
例えば、docsがソースディレクトリ、docs/_build/htmlがビルド成果物出力ディレクトリの場合は、下記のようになります。
sphinx-autobuild docs docs/_build/html
上記のコマンドを実行したあとで、http://127.0.0.1:8000 にアクセスすると、ビルドされたHTML文書にアクセスできます。HTML文書が変更されると、ブラウザが自動的に更新されます。なお、ホスト名やポート番号は、sphinx-autobuildのコマンドラインオプションで変更できます。
sphinx-autobuildを終了するには、Ctrl+Cを入力します。
上記コマンドを実行するシェルスクリプトやバッチファイルを作成しておくと楽です。sphinx-autobuildのドキュメントにあるとおり、Sphinxが生成したMakefileに下記のターゲットを追加するのもよいと思います。
livehtml:
sphinx-autobuild -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html