Closes #925: Allow list-typed config values to be provided on the command line,

like ``-D key=val1,val2``.

CHANGES

@@ -7,6 +7,9 @@ New features
 * PR#202: Allow "." and "~" prefixed references in ``:param:`` doc fields
   for Python.
 
+* #925: Allow list-typed config values to be provided on the command line,
+  like ``-D key=val1,val2``.
+
 Bugs fixed
 ----------
 

doc/invocation.rst

@@ -124,13 +124,22 @@ The :program:`sphinx-build` script has several options:
 .. option:: -D setting=value
 
    Override a configuration value set in the :file:`conf.py` file.  The value
-   must be a string or dictionary value.  For the latter, supply the setting
-   name and key like this: ``-D latex_elements.docclass=scrartcl``.  For boolean
-   values, use ``0`` or ``1`` as the value.
+   must be a number, string, list or dictionary value.
+
+   For lists, you can separate elements with a comma like this: ``-D
+   html_theme_path=path1,path2``.
+
+   For dictionary values, supply the setting name and key like this:
+   ``-D latex_elements.docclass=scrartcl``.
+
+   For boolean values, use ``0`` or ``1`` as the value.
 
    .. versionchanged:: 0.6
       The value can now be a dictionary value.
 
+   .. versionchanged:: 1.3
+      The value can now also be a list value.
+
 .. option:: -A name=value
 
    Make the *name* assigned to *value* in the HTML templates.

sphinx/application.py

@@ -122,7 +122,7 @@ class Sphinx(object):
             self.config.setup(self)
 
         # now that we know all config values, collect them from conf.py
-        self.config.init_values()
+        self.config.init_values(self.warn)
 
         # check the Sphinx version if requested
         if self.config.needs_sphinx and \

sphinx/cmdline.py

@@ -173,14 +173,11 @@ def main(argv):
                 print >>sys.stderr, ('Error: -D option argument must be '
                                      'in the form name=value.')
                 return 1
-            try:
-                val = int(val)
-            except ValueError:
-                if likely_encoding and isinstance(val, bytes):
-                    try:
-                        val = val.decode(likely_encoding)
-                    except UnicodeError:
-                        pass
+            if likely_encoding and isinstance(val, bytes):
+                try:
+                    val = val.decode(likely_encoding)
+                except UnicodeError:
+                    pass
             confoverrides[key] = val
         elif opt == '-A':
             try:

sphinx/config.py

@@ -248,12 +248,33 @@ class Config(object):
                      'Please use Unicode strings, e.g. %r.' % (name, u'Content')
                 )
 
-    def init_values(self):
+    def init_values(self, warn):
         config = self._raw_config
         for valname, value in self.overrides.iteritems():
             if '.' in valname:
                 realvalname, key = valname.split('.', 1)
                 config.setdefault(realvalname, {})[key] = value
+                continue
+            elif valname not in self.values:
+                warn('unknown config value %r in override, ignoring' % valname)
+                continue
+            defvalue = self.values[valname][0]
+            if isinstance(defvalue, dict):
+                warn('cannot override dictionary config setting %r, '
+                     'ignoring (use %r to set individual elements)' %
+                     (valname, valname + '.key=value'))
+                continue
+            elif isinstance(defvalue, list):
+                config[valname] = value.split(',')
+            elif isinstance(defvalue, (int, long)):
+                try:
+                    config[valname] = int(value)
+                except ValueError:
+                    warn('invalid number %r for config value %r, ignoring'
+                         % (value, valname))
+            elif not isinstance(defvalue, (str, unicode)):
+                warn('cannot override config setting %r with unsupported type, '
+                     'ignoring' % valname)
             else:
                 config[valname] = value
         for name in config:

sphinx/ext/todo.py

@@ -171,4 +171,3 @@ def setup(app):
     app.connect('doctree-read', process_todos)
     app.connect('doctree-resolved', process_todo_nodes)
     app.connect('env-purge-doc', purge_todos)
-