Sphinx 0.6.2 にアップグレードしたときのメモ

約一年ぶりに Sphinx を最新版に…しようとしたら色々苦労したので、変更点や手順をメモとして残しておく。

Sphinx 0.6.2 & Jinja2 2.1.1

easy_install でインストールしようとしたが、Jinja2 のセットアップ・スクリプトがうまく動いていないらしく、Jinja2 に依存している Sphinx もインストールできない。原因を調べる気力はないので、ソースコードからビルドしてインストールすることにした。

まずは Jinja2 2.1.1 をビルドしてインストール。

% curl -LO http://pypi.python.org/packages/source/J/Jinja2/Jinja2-2.1.1.tar.gz
% tar xvzf Jinja2-2.1.1.tar.gz
% cd Jinja2-2.1.1
% sudo python setup.py install

つづいて Sphinx 0.6.2

% curl -LO http://pypi.python.org/packages/source/S/Sphinx/Sphinx-0.6.2.tar.gz
% tar xvzf Sphinx-0.6.2.tar.gz
% cd Sphinx-0.6.2
% sudo python setup.py install

sphinx.builder

Sphinx 0.6.2 では sphinx.builder が非推奨扱いになっていた (changeset:254e0ff435e8)。

Running Sphinx v0.6.2
docs/ja/source/../../sphinxext/__init__.py:1:
DeprecationWarning: The sphinx.builder module is deprecated; please import builders from the respective sphinx.builders submodules.

次のバージョンでは削除されているようだし、モジュール名を適切に直す。

-from sphinx.builder import StandaloneHTMLBuilder
+from sphinx.builders.html import StandaloneHTMLBuilder

UnicodeDecodeError

今度は、日本語を含むドキュメントを変換しようとすると UnicodeDecodeError が発生する。

Exception occurred:
  File "/Library/Python/2.5/site-packages/Sphinx-0.6.2-py2.5.egg/sphinx/themes/basic/layout.html", line 19, in block "rootrellink"
    <li><a href="{{ pathto(master_doc) }}">{{ shorttitle|e }}</a>{{ reldelim1 }}</li>
UnicodeDecodeError: 'ascii' codec can't decode byte 0xe3 in position 8: ordinal not in range(128)
The full traceback has been saved in /var/folders/Xg/XgsbIugsGWiYSnTBrMoebU+++TI/-Tmp-/sphinx-err-cfE9NN.log, if you want to report the issue to the author.
Please also report this if it was a user error, so that a better error message can be provided next time.

どうやら、conf.py に str で日本語を書いていたのが原因らしい。unicode リテラルで書き直したらうまくいった。Jinja2 の Unicode 対応が原因だろうか。