Set the default encoding to `utf-8-sig` to handle files with a

UTF-8 BOM correctly.

CHANGES

@@ -1,6 +1,9 @@
 Release 0.6.2 (in development)
 ==============================
 
+* Set the default encoding to ``utf-8-sig`` to handle files with a
+  UTF-8 BOM correctly.
+
 * #178: apply ``add_function_parentheses`` config value to C
   functions as promised.
 

doc/config.rst

@@ -77,7 +77,7 @@ General configuration
 .. confval:: source_encoding
 
    The encoding of all reST source files.  The recommended encoding, and the
-   default value, is ``'utf-8'``.
+   default value, is ``'utf-8-sig'``.
 
    .. versionadded:: 0.5
       Previously, Sphinx accepted only UTF-8 encoded sources.

sphinx/config.py

@@ -37,7 +37,7 @@ class Config(object):
 
         master_doc = ('contents', 'env'),
         source_suffix = ('.rst', 'env'),
-        source_encoding = ('utf-8', 'env'),
+        source_encoding = ('utf-8-sig', 'env'),
         unused_docs = ([], 'env'),
         exclude_dirs = ([], 'env'),
         exclude_trees = ([], 'env'),

sphinx/environment.py

@@ -52,7 +52,7 @@ default_settings = {
     'cloak_email_addresses': True,
     'pep_base_url': 'http://www.python.org/dev/peps/',
     'rfc_base_url': 'http://tools.ietf.org/html/',
-    'input_encoding': 'utf-8',
+    'input_encoding': 'utf-8-sig',
     'doctitle_xform': False,
     'sectsubtitle_xform': False,
 }

tests/root/bom.txt

@@ -0,0 +1,5 @@
+File with UTF-8 BOM
+===================
+
+This file has a UTF-8 "BOM".
+

tests/root/contents.txt

@@ -17,6 +17,7 @@ Contents:
    includes
    markup
    desc
+   bom
    math
    autodoc
    autosummary

tests/test_build.py

@@ -41,7 +41,7 @@ ENV_WARNINGS = """\
 %(root)s/images.txt:9: WARNING: image file not readable: foo.png
 %(root)s/images.txt:23: WARNING: nonlocal image URI found: \
 http://www.python.org/logo.png
-%(root)s/includes.txt:: (WARNING/2) Encoding 'utf-8' used for reading \
+%(root)s/includes.txt:: (WARNING/2) Encoding 'utf-8-sig' used for reading \
 included file u'wrongenc.inc' seems to be wrong, try giving an :encoding: option
 %(root)s/includes.txt:56: WARNING: download file not readable: nonexisting.png
 """
@@ -115,6 +115,9 @@ HTML_XPATH = {
         ".//div[@class='footer']": 'Georg Brandl & Team',
         ".//a[@href='http://python.org/']": '',
     },
+    'bom.html': {
+        ".//title": " File with UTF-8 BOM",
+    },
     '_static/statictmpl.html': {
         ".//project": 'Sphinx <Tests>',
     },