CUBE SUGAR CONTAINER

技術系のこと書きます。

Sphinx: sphinx-autobuild で執筆作業の効率を上げる

先日 SphinxCon JP 2015 で発表の機会に恵まれたんだけど、意外と sphinx-autobuild について知られていなかったようなのでブログにも書いてみることにする。

まず、内容を確認するのに HTML を使っている場合、通常であれば Sphinx の執筆作業は以下の工程の繰り返しになるとおもう。 この繰り返しは本当にめんどうくさいから、執筆への集中を阻害する原因になる。

  1. ドキュメントのソースファイルを編集する
  2. Sphinx でビルドする
  3. ブラウザにフォーカスを移す
  4. ブラウザをリロードする
  5. 内容を確認する

そこで 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

初期状態ではこんなページができる。

f:id:momijiame:20151128134513p:plain

これでやっと 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/

こんなかんじ。

f:id:momijiame:20151128135150p:plain

コマンド長くない?

ただ、毎回 sphinx-autobuild の長いコマンドを叩くのはこれもまためんどう。 Sphinx が生成した Makefile の中に、それ用のターゲットを作っておくといい。 今回の例であれば、こんなかんじのやつ。

livereload:
    sphinx-autobuild -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml

こうしておけば簡単に sphinx-autobuild を立ち上げることができる。

$ make livereload

めでたしめでたし。

備考

イベントの詳細についてはこちら。

sphinxjp.connpass.com

発表資料はこちら。

speakerdeck.com