Sphinx のビルドシステム置き換え

ドキュメンテーションビルダーである Sphinx の標準ビルドシステムは make ですが、 Mac OSX や Windows では標準的には利用できないため、その代替について考えてみます。 ９月に開催された Python Conference Japan 2012 で発表した内容の抜粋になります。

• pyconjp で発表してきた #pyconjp

目次

• SCons を使う
• waf を使う
• 終わりに

SCons を使う

Python 製のビルドツールとしては SCons が有名だと思います。 基本的には C 言語で記述されたソースファイルをオブジェクトファイルにコンパイルし、 それらをリンクしてライブラリやアプリケーションをビルドするために使います。

これらの過程ではファイル同士の依存性を扱う必要がありますが、SCons ではその依存性を Python で記述できるようになっています。 Sphinx にもソースとなるテキストファイル (reST) と生成ターゲットとなるファイル (HTML や PDF など) の間には 依存関係がありますので、ビルドツールをうまく適用できると、ファイルを変更する度に必要なファイルだけを更新できます。

SCons では SConstruct というファイルにビルド設定を記述して scons コマンドでビルドを実行できます。 たとえば、 make html を置き換えるスクリプトは次のように記述できます。

SConstruct:

# See <https://bitbucket.org/zondo/sphinx-scons>

import os

# Sphinx command line usage.
sphinxcmd = """
%(builder)s -b %(name)s -d %(doctrees)s %(options)s %(srcdir)s %(targetdir)s
""".strip()

env = Environment(ENV = {"PATH" : os.environ["PATH"]})

sphinxconf = 'conf.py'
builder = 'sphinx-build'
name = 'html'
srcdir = '.'
builddir = '_build'
doctrees = os.path.join(builddir, "doctrees")
options = ''

target = Dir(name, builddir)
targetdir = str(target)

env.Command(name, sphinxconf, sphinxcmd % locals(), chdir=True)

これは HTML だけをターゲットにした場合ですが、よりしっかりと作成されたプロジェクトもあります。

• sphinx-scons - bitbucket.org

  A simple SCons (http://www.scons.org) script to help with building Sphinx documentation.

残念ながら現在の開発があまり活発とは言えませんが、自力でゼロから始めるとすれば参考になるでしょう。

waf を使う

SCons から派生したツールとして Waf というビルドツールもあります。 Waf はインストールが非常に簡単で、プロジェクトのサイトからパッケージをダウンロードし、 実行ビットを立てて PATH に置くだけです。 virtualenv と組み合わせるならば SCons よりも Waf の方が断然オススメです。

先ほどと同じように、 make html を置き換えるスクリプトは次のように記述できます。

wscript:

import os

top = '.'
out = '_build'

# Sphinx command line usage.
sphinxcmd = """
%(builder)s -b %(name)s -d %(doctrees)s %(options)s %(srcdir)s %(targetdir)s
""".strip()


def configure(ctx):
    ctx.find_program('sphinx-build')


def document(ctx):
    sphinxconf = 'conf.py'
    builder = 'sphinx-build'
    name = 'html'
    builddir = out
    doctrees = os.path.join(builddir, "doctrees")
    options = ''
    srcdir = '.'
    targetdir = os.path.join(builddir, name)
    ctx.exec_command(sphinxcmd % locals(), cwd='.')

waf は関数を定義するとタスクになるので、個人的にはこちらの方が好きです。 たとえば、生成された HTML を ZIP にまとめるには次の記事のように実行できます。

• waf を使って Sphinx で生成した HTML を ZIP にまとめる (2012年2月16日)

終わりに

Sphinx の標準ビルドシステムは make ですが、その代替を考えてみました。 Python で記述されたツールなので、Python 製のビルドツールが適していると思います。 とはいえ、現状でも sphinx-build が提供されていますので、 make 層の置き換えだけならそんなに難しくないのかも!? 課題はパッケージングとそのメンテナンスにありそうです。

なお、Windows では make.bat というファイル名にしておくことで擬似的に make コマンドのように呼び出せますが、 ファイルの中身は完全に別物になってしまいますので管理上は好ましくありません。 スムーズに移行できそうな方法があるなら模索しておきたいところです。