Make sure the encoding used in logging

For now, December 2013, following customizing seems not required any more.

(All contents on this page below might be obsolete.)

When Sphinx met the error on the file named with non US-ASCII characters, UnicodeEncodeError will be re-raised and we can’t know what’s wrong.

With Microsoft Windows and Python 2, you can only extend the characters included in your local encoding. Other operating system may or may not have similar limitation. This failure depends on Python 2.

With Python 3 for the future, this problem will be resolved [PythonIssue3080] . And also, we don’t have to use sitecustomize.py.

Using sitecustomize.py

Make the file sitecustomize.py which contains following code, and place it at the folder mentioned in PEP370

sitecustomize.py

# coding: utf-8
import sys
sys.setdefaultencoding('mbcs') # 'mbcs' is available only with MS Windows.
                               # Replace the encoding your OS uses.

The Python code to show the path to place the file on Windows:

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

Using the patch for Sphinx

If you use developing version of Sphinx, you may use the patch http://paste.pocoo.org/show/355901/ .