先日 SphinxCon JP 2015 で発表の機会に恵まれたんだけど、意外と sphinx-autobuild について知られていなかったようなのでブログにも書いてみることにする。
まず、内容を確認するのに HTML を使っている場合、通常であれば Sphinx の執筆作業は以下の工程の繰り返しになるとおもう。 この繰り返しは本当にめんどうくさいから、執筆への集中を阻害する原因になる。
- ドキュメントのソースファイルを編集する
- Sphinx でビルドする
- ブラウザにフォーカスを移す
- ブラウザをリロードする
- 内容を確認する
そこで sphinx-autobuild を使うと (2) から (4) までの作業を自動化してくれる。 これで執筆に集中できるから効率も上がるというもの。
使ってみよう
検証した環境には Mac OS X を使っている。
$ sw_vers ProductName: Mac OS X ProductVersion: 10.11.1 BuildVersion: 15B42
ここからはちょっと下準備が長くなる。
インストール
まずは sphinx 本体と sphinx-autobuild を pip でインストールしておく。
$ pip install sphinx sphinx-autobuild
動作確認に使うドキュメントを作る
Sphinx でドキュメントを書き始める際の基本となる sphinx-quickstart コマンドで最初に必要なファイルを自動で作ってもらう。 デフォルトのままにしている箇所は省略した。
$ sphinx-quickstart ...(省略)... You have two options for placing the build directory for Sphinx output. Either, you use a directory "_build" within the root path, or you separate "source" and "build" directories within the root path. > Separate source and build directories (y/n) [n]: y ...(省略)... The project name will occur in several places in the built documentation. > Project name: helloworld > Author name(s): @momijiame Sphinx has the notion of a "version" and a "release" for the software. Each version can have multiple releases. For example, for Python the version is something like 2.5 or 3.0, while the release is something like 2.5.1 or 3.0a1. If you don't need this dual structure, just set both to the same value. > Project version: 0.0.1 > Project release [0.0.1]: If the documents are to be written in a language other than English, you can select a language here by its language code. Sphinx will then translate text that it generates into that language. For a list of supported codes, see http://sphinx-doc.org/config.html#confval-language. > Project language [en]: ja ...(省略)... A Makefile and a Windows command file can be generated for you so that you only have to run e.g. `make html' instead of invoking sphinx-build directly. > Create Makefile? (y/n) [y]: > Create Windows command file? (y/n) [y]: n ...(省略)...
これで必要なファイルが一通りつくられる。
$ tree . ├── Makefile ├── build └── source ├── _static ├── _templates ├── conf.py └── index.rst 4 directories, 3 files
ビルドできることを確認する
まずは最初の状態で HTML にビルドできることを確認しておこう。
$ make singlehtml
ビルドできたら生成されたページをブラウザで開く。
$ open build/singlehtml/index.html
初期状態ではこんなページができる。
これでやっと sphinx-autobuild を使う準備ができた。
sphinx-autobuild
sphinx-autobuild を使うには同名のコマンドを利用する。 ひとまず出力のフォーマットと、監視するドキュメントのソースファイルの入ったディレクトリと、出力先のディレクトリを指定する。
$ sphinx-autobuild -b singlehtml source build/singlehtml [I 151128 13:21:35 server:271] Serving on http://127.0.0.1:8000 [I 151128 13:21:35 handlers:58] Start watching changes [I 151128 13:21:35 handlers:60] Start detecting changes
コマンドの出力からも分かるように、これでビルドされたドキュメント (上記であれば build/singlehtml) の内容を公開する Web サーバがローカルホストで立ち上がる。 これをブラウザで開いておく。
$ open http://127.0.0.1:8000/
この状態でドキュメントのソースファイルを編集してみよう。
$ echo "Hello, World" >> source/index.rst
するとソースファイルの変更を sphinx-autobuild が検出して再ビルドが走り、ビルドした内容を Web サーバが反映してくれる。
$ sphinx-autobuild -b singlehtml source build/singlehtml [I 151128 13:21:35 server:271] Serving on http://127.0.0.1:8000 [I 151128 13:21:35 handlers:58] Start watching changes [I 151128 13:21:35 handlers:60] Start detecting changes ...(省略)... +--------- source/index.rst changed --------------------------------------------- | Running Sphinx v1.3.1 | loading translations [ja]... done | loading pickled environment... done | building [mo]: targets for 0 po files that are out of date | building [singlehtml]: all documents | 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 | assembling single document... | writing... done | writing additional files... | copying static files... done | copying extra files... done | dumping object inventory... done | build succeeded. +-------------------------------------------------------------------------------- [I 151128 13:25:00 handlers:91] Reload 1 waiters: None [I 151128 13:25:00 handlers:131] Browser Connected: http://127.0.0.1:8000/
こんなかんじ。
コマンド長くない？
ただ、毎回 sphinx-autobuild の長いコマンドを叩くのはこれもまためんどう。 Sphinx が生成した Makefile の中に、それ用のターゲットを作っておくといい。 今回の例であれば、こんなかんじのやつ。
livereload:
sphinx-autobuild -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
こうしておけば簡単に sphinx-autobuild を立ち上げることができる。
$ make livereload
めでたしめでたし。
備考
イベントの詳細についてはこちら。
発表資料はこちら。
