======================================
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 <http://www.python.org/dev/peps/pep-0370/>`_ 

``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')

.. note:

	If you don't use MS Windows, see PEP 370 above.

	'mbcs' generally would be replaced with 'utf-8', but you should make sure.

.. note:

	Of course you can add any code you want in ``sitecustomize.py`` .

------------------------------
Using the patch for Sphinx
------------------------------

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