2012年2月16日

waf を使って Sphinx で生成した HTML を ZIP にまとめる

ビルドツールである waf を使って、 Sphinx で生成した HTML ファイルを ZIP 形式にまとめるメモです。
コマンドラインで次のように実行すると、Sphinx でビルドして ZIP が作成されます。
$ waf configure build dist

(出力省略)

New archive created: sphinx-project-1.0.0.zip
'dist' finished successfully (7.701s)
Sphinx に関してはこちらの記事でも紹介されています。
  • Sphinx は Python で作成されており、元々は Python 言語のドキュメント作成用に作られたものですが、 必ずしもドキュメント作成の対象言語を Python のみに限定しているわけではありません。 場合によってはプログラマーの作成するドキュメントのみが対象というわけですらありません。 Sphinx の利用者は数多くおり、本をまるごと Sphinx で執筆する人もいます。

環境の準備

まずは Sphinx と waf を使えるようにします。 virtualenv で独立した環境を作成し、ツールをインストールします。
$ virtualenv --distribute waf-sphinx
$ cd $_
$ cat <<EOF >requirements.txt
Sphinx
EOF
$ . bin/activate
$ pip install -r requirements.txt
$ curl http://waf.googlecode.com/files/waf-1.6.11 >bin/waf
$ chmod +x bin/waf
Sphinx でプロジェクトを作成したり、何らかのドキュメントを構成する方法は冒頭の IBM developerWorks の記事を参照してください。

wscript を書く

wscriptmake における Makefile のようなものです。 関数がアクションになります。 デフォルトで定義されているアクション名の関数を定義するのが基本的な記述になります。 ここでは次の3つの関数を定義します。
  • configure: ツールが存在することを確認する
  • build: 処理を実行する
  • dist: パッケージにまとめる
wscript
APPNAME = 'sphinx-project'
VERSION = '1.0.0'

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

def build(bld):
    # Sphinx 用のテキストは doc/ ディレクトリにあると仮定。
    bld.exec_command(['make', 'html'], cwd='doc')

def dist(ctx):
    ctx.algo = 'zip'
    ctx.files = ctx.path.ant_glob(['doc/build/_html/**/*'])
    ctx.base_path = ctx.path.find_dir('doc/_build/html')
順番に実行していきます。
$ waf configure
$ waf build
$ waf dist
New archive created: sphinx-project-1.0.0.zip
'dist' finished successfully (7.701s)
APPNAMEVERSION で指定した ZIP アーカイブができました。 ctx.algo のデフォルトは bz2 なので、 圧縮効率を高めたい場合には何も指定しなければ自動的に処理してくれます。 base_path を指定することで、特定のディレクトリ以下のファイルに絞ってアーカイブを作成できます。 何も指定しない場合は、カレントディレクトリ以下のファイルが対象になります。 バックアップファイルやオブジェクトファイルなど、除外するものとして有名な拡張子は対象外となります。 excl で明示することも可能です。 たとえば、Sphinx で生成した場合はソースを含めない、といったカスタマイズも可能です。

終わりに

探してみると英語のフォーラムにも似たような投稿がありました。 だいたいの人が考えることは一緒、と。
wscript を記述するときは API ドキュメントを読みながら、というのがちょっと大変かもしれませんね。
サクッと ZIP にまとめられると嬉しいなぁ、と思っていたので、自分としては結構嬉しい発見でした。
コメントを投稿