buildout を利用して Sphinx 環境を構築する

複数人で Sphinx 文章を扱う場合、ネックになりがちなのが各々のマシンに Sphinx をインストールすることです。特に、Sphinx に加えて外部の Sphinx 拡張を利用している場合は混乱が生じがちです。

ここでは開発環境構築ツールである buildout を利用して、Sphinx 環境の構築を行います。

buildout の導入

buildout は以下の 2つのファイルで構成されます。

bootstrap.py

buildout の実行環境を構築するスクリプトです。各マシン上で最初に 1度だけ実行します。

Web 上に公開されているものを wget コマンドで取得します:

$ wget 'http://downloads.buildout.org/2/bootstrap.py'
buildout.cfg
環境定義のための設定ファイルです。インストールするパッケージなどを記述することができます。vi などのテキストエディタで作成します。

buildout環境にSphinxをインストールするには、 bootstrap.py をダウンロードした後、空のディレクトリにbootstrap.pyを置いて以下のコマンドを実行します。

$ python bootstrap.py init Sphinx

Creating directory '/home/shimizukawa/sphinxenv/eggs'.
Getting distribution for 'setuptools'.
warning: no files found matching 'entries*' under directory 'setuptools/tests'
warning: no files found matching 'Makefile' under directory 'docs'
warning: no files found matching 'indexsidebar.html' under directory 'docs'
Got setuptools 2.0.
Upgraded:
  setuptools version 2.0;
restarting.
Generated script '/home/shimizukawa/sphinxenv/bin/buildout'.
Getting distribution for 'zc.recipe.egg>=2.0.0a3'.
Got zc.recipe.egg 2.0.1.
Uninstalling py.
Installing py.
Getting distribution for 'sphinx'.
Got sphinx 1.2.
Getting distribution for 'docutils>=0.7'.
warning: no files found matching 'MANIFEST'
warning: no files found matching '*' under directory 'extras'
warning: no previously-included files matching '.cvsignore' found under directory '*'
warning: no previously-included files matching '*.pyc' found under directory '*'
warning: no previously-included files matching '*~' found under directory '*'
warning: no previously-included files matching '.DS_Store' found under directory '*'
zip_safe flag not set; analyzing archive contents...
docutils.parsers.rst.directives.misc: module references __file__
docutils.writers.docutils_xml: module references __path__
docutils.writers.html4css1.__init__: module references __file__
docutils.writers.pep_html.__init__: module references __file__
docutils.writers.s5_html.__init__: module references __file__
docutils.writers.latex2e.__init__: module references __file__
docutils.writers.odf_odt.__init__: module references __file__
Got docutils 0.11.
Getting distribution for 'Jinja2>=2.3'.
warning: no files found matching '*' under directory 'custom_fixers'
warning: no previously-included files matching '*' found under directory 'docs/_build'
warning: no previously-included files matching '*.pyc' found under directory 'jinja2'
warning: no previously-included files matching '*.pyc' found under directory 'docs'
warning: no previously-included files matching '*.pyo' found under directory 'jinja2'
warning: no previously-included files matching '*.pyo' found under directory 'docs'
Installing Jinja2 2.7.1
Caused installation of a distribution:
jinja2 2.7.1
with a different project name.
Got jinja2 2.7.1.
Getting distribution for 'Pygments>=1.2'.
Got pygments 1.6.
Getting distribution for 'markupsafe'.
Installing MarkupSafe 0.18
Caused installation of a distribution:
markupsafe 0.18
with a different project name.
Got markupsafe 0.18.
Generated script '/home/shimizukawa/sphinxenv/bin/sphinx-apidoc'.
Generated script '/home/shimizukawa/sphinxenv/bin/sphinx-build'.
Generated script '/home/shimizukawa/sphinxenv/bin/sphinx-quickstart'.
Generated script '/home/shimizukawa/sphinxenv/bin/sphinx-autogen'.
Generated interpreter '/home/shimizukawa/sphinxenv/bin/py'.

コマンドを実行すると bin/ 以下に Sphinx の各種スクリプトがセットアップされます。

$ ls bin/
buildout  py  sphinx-apidoc  sphinx-autogen  sphinx-build  sphinx-quickstart

ここからは通常の Sphinx の利用方法にしたがって、ドキュメントを書いていくことができます。通常は Sphinx プロジェクトをバージョン管理するなどして共有しますが、これに加えて buildout の 2ファイルも共有することで、簡単に環境を再現することができます。

なお、sphinx-quickstart で生成される Makefile, make.bat は sphinx-build コマンドのパス指定がないため、以下のように書き換えます。

--- Makefile.orig
+++ Makefile
@@ -3,7 +3,7 @@

 # You can set these variables from the command line.
 SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
+SPHINXBUILD   = bin/sphinx-build
 PAPER         =
 BUILDDIR      = _build

--- make.bat.orig
+++ make.bat
@@ -3,7 +3,7 @@
 REM Command file for Sphinx documentation

 if "%SPHINXBUILD%" == "" (
-       set SPHINXBUILD=sphinx-build
+       set SPHINXBUILD=bin/sphinx-build
 )
 set BUILDDIR=_build
 set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .

Sphinx 拡張や拡張テーマを利用する

Sphinx 拡張や拡張テーマを使う場合は、buildout.cfg にパッケージ名を追記することで拡張パッケージをインストールすることができます。例として、sphinxjp.themes.bizstyle を利用する場合は buildout.cfg を以下のように書き換えます。

[buildout]
parts = doc

[doc]
recipe = zc.recipe.egg
eggs =
     sphinx
     sphinxjp.themes.bizstyle
interpreter = py

buildout.cfg を書き換えた後、再度 bin/buildout コマンドを実行します。

$ bin/buildout
Uninstalling doc.
Installing doc.
Getting distribution for 'sphinxjp.themes.bizstyle'.
Got sphinxjp.themes.bizstyle 0.1.5.
Getting distribution for 'sphinxjp.themecore'.
Got sphinxjp.themecore 0.1.3.
Generated script '/home/katsuwo/tmp/bin/sphinx-apidoc'.
Generated script '/home/katsuwo/tmp/bin/sphinx-build'.
Generated script '/home/katsuwo/tmp/bin/sphinx-quickstart'.
Generated script '/home/katsuwo/tmp/bin/sphinx-autogen'.
Generated interpreter '/home/katsuwo/tmp/bin/py'.

buildout コマンドにより sphinxjp.themes.bizstyle パッケージがインストールされました。さらに依存関係のある sphinxjp.themecore もインストールされます。

あとは conf.py の設定を書き換えるだけで、Sphinx 拡張を利用することができます。

注釈

日本語 PDF パッチ適用済み Sphinx を利用する

Sphinx-1.2より以前のバージョンを使用したい場合、かつ日本語PDF出力を行いたい場合は、以下のように buildout.cfg を書き換えることで日本語 PDF パッチが適用された Sphinx-1.1.3 を利用することができます。

[buildout]
find-links = https://bitbucket.org/sphinxjp/website/downloads/Sphinx-1.1.3sphinxjp-latex.tar.gz
versions = versions
parts = py

[py]
recipe = zc.recipe.egg
eggs =
    sphinx
    sphinxjp.themes.bizstyle
interpreter = py

[versions]
sphinx = 1.1.3sphinxjp-latex