Improve the handling of non-Unicode strings in the configuration:

warn about non-ascii bytestrings, and give nicer messages if unicode errors
occur.

CHANGES

@@ -1,6 +1,8 @@
 Release 0.6.4 (in development)
 ==============================
 
+* Improve the handling of non-Unicode strings in the configuration.
+
 * #316: Catch OSErrors occurring when calling graphviz with
   arguments it doesn't understand.
 

sphinx/application.py

@@ -92,6 +92,7 @@ class Sphinx(object):
         # read config
         self.tags = Tags(tags)
         self.config = Config(confdir, CONFIG_FILENAME, confoverrides, self.tags)
+        self.config.check_unicode(self.warn)
 
         # load all extension modules
         for extension in self.config.extensions:

sphinx/builders/html.py

@@ -656,7 +656,14 @@ class StandaloneHTMLBuilder(Builder):
         self.app.emit('html-page-context', pagename, templatename,
                       ctx, event_arg)
 
-        output = self.templates.render(templatename, ctx)
+        try:
+            output = self.templates.render(templatename, ctx)
+        except UnicodeError:
+            self.warn("a Unicode error occurred when rendering the page %s. "
+                      "Please make sure all config values that contain "
+                      "non-ASCII content are Unicode strings." % pagename)
+            return
+
         if not outfilename:
             outfilename = self.get_outfilename(pagename)
         # outfilename's path is in general different from self.outdir

sphinx/builders/latex.py

@@ -102,7 +102,13 @@ class LaTeXBuilder(Builder):
             doctree.settings.title = title
             doctree.settings.docname = docname
             doctree.settings.docclass = docclass
-            docwriter.write(doctree, destination)
+            try:
+                docwriter.write(doctree, destination)
+            except UnicodeError:
+                self.warn("a Unicode error occurred when writing the output. "
+                          "Please make sure all config values that contain "
+                          "non-ASCII content are Unicode strings." % pagename)
+                return
             self.info("done")
 
     def assemble_doctree(self, indexfile, toctree_only, appendices):

sphinx/config.py

@@ -10,9 +10,13 @@
 """
 
 import os
+import re
 from os import path
 
 from sphinx.util import make_filename
+from sphinx.errors import ConfigError
+
+nonascii_re = re.compile(r'[\x80-\xff]')
 
 
 class Config(object):
@@ -112,20 +116,34 @@ class Config(object):
         self.values = Config.config_values.copy()
         config = {}
         if dirname is not None:
-            config['__file__'] = path.join(dirname, filename)
+            config_file = path.join(dirname, filename)
+            config['__file__'] = config_file
             config['tags'] = tags
             olddir = os.getcwd()
             try:
                 os.chdir(dirname)
                 execfile(config['__file__'], config)
+            except SyntaxError, err:
+                raise ConfigError('There is a syntax error in your '
+                                  'configuration file: ' + str(err))
             finally:
                 os.chdir(olddir)
+
         self._raw_config = config
         # these two must be preinitialized because extensions can add their
         # own config values
         self.setup = config.get('setup', None)
         self.extensions = config.get('extensions', [])
 
+    def check_unicode(self, warn):
+        # check all string values for non-ASCII characters in
+        # bytestrings, since that can
+        for name, value in self._raw_config.iteritems():
+            if isinstance(value, str) and nonascii_re.search(value):
+                warn('the config value %r is set to a string with non-ASCII '
+                     'characters; this can lead to Unicode errors occurring. '
+                     'Please use Unicode strings, e.g. u"Content".' % name)
+
     def init_values(self):
         config = self._raw_config
         for valname, value in self.overrides.iteritems():

sphinx/errors.py

@@ -44,5 +44,9 @@ class ExtensionError(SphinxError):
         return parent_str
 
 
+class ConfigError(SphinxError):
+    category = 'Configuration error'
+
+
 class ThemeError(SphinxError):
     category = 'Theme error'

tests/test_config.py

@@ -12,7 +12,8 @@
 
 from util import *
 
-from sphinx.application import ExtensionError
+from sphinx.config import Config
+from sphinx.errors import ExtensionError, ConfigError
 
 
 @with_app(confoverrides={'master_doc': 'master', 'nonexisting_value': 'True',
@@ -77,3 +78,19 @@ def test_extension_values(app):
                'html_title', 'x', True)
     raises_msg(ExtensionError, 'already present', app.add_config_value,
                'value_from_ext', 'x', True)
+
+
+@with_tempdir
+def test_errors_warnings(dir):
+    # test the error for syntax errors in the config file
+    write_file(dir / 'conf.py', 'project = \n')
+    raises_msg(ConfigError, 'conf.py', Config, dir, 'conf.py', {}, None)
+
+    # test the warning for bytestrings with non-ascii content
+    write_file(dir / 'conf.py', '# -*- coding: latin-1\nproject = "foo\xe4"\n')
+    cfg = Config(dir, 'conf.py', {}, None)
+    warned = [False]
+    def warn(msg):
+        warned[0] = True
+    cfg.check_unicode(warn)
+    assert warned[0]