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

------------------------
下記の内容について
------------------------
確認はしておりませんが 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 <http://www.python.org/dev/peps/pep-0370/>`_ 
が指定する場所に配置します。

``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 のリポジトリから引っ張って使っている場合は
`清水川さんによるパッチ <http://paste.pocoo.org/show/355901/>`_\ を活用いただけます。