記録時の文字符号化法指定

下記の内容について

確認はしておりませんが 2013年12月の時点で、下記の処置は必要なくなったものと思われます。

(以下過去の内容)

特段の準備をしていない場合、日本語のファイル名や項目名などでエラーが発生すると UnicodeEncodeError が多重発生して原因がつかめなくなってしまいます。

これは Sphinx が一部を除いて US-ASCII しか使わないことを前提に設計されているためです。ここで紹介する作業により日本語のファイル名なども使えるようになります。

ただし Windows の場合は日本語版 Windows であれば Microsoft Shift JIS の範囲の文字までしか適用範囲が拡がりません。他言語版 Windows でも似たような制限が課されます。こちらは Python (2.x) 自体の不具合が原因で簡単に解決できるものではありません。

Python 3 においては解決する方向で動いているようです[PythonIssue3080]。また、Python 3 に Sphinx 自体が移行できたならこの作業は不要になります( sys.setdefaultencoding メソッド自体が存在しない )。

Windows 以外の事情についてはそれぞれ違うと思われますが、おそらくは utf-8 によって全ての文字が使えるか、euc-jp の範囲に限定されるかのどちらかでしょう。

sitecustomize.pyを使う方法

次の内容が記述されたファイルに sitecustomize.py という名前を付けて PEP370 が指定する場所に配置します。

sitecustomize.py の内容:

# coding: utf-8
import sys
sys.setdefaultencoding('mbcs') # Windows 以外では mbcs を適宜置き換えてください

Windows で配置場所を表示する Python スクリプト:

import os.path
import sys
print os.path.join(os.path.expandvars('${APPDATA}'),
                                      'Python',
                                      'Python2'+str(sys.version_info.minor),
                                      'site-packages')

※ Windows 以外の配置場所については前述の PEP370 を参照下さい。

※ もちろん必要に応じて他の内容を sitecustomize.py に加えても構いません。

提供されているパッチを使う方法

Sphinx の 1.0.7 とかの公式安定版ではなく、Mercurial のリポジトリから引っ張って使っている場合は 清水川さんによるパッチを活用いただけます。