diff --git a/CHANGES b/CHANGES index 34e7158e6..3b7cdf79f 100644 --- a/CHANGES +++ b/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 ---------- diff --git a/doc/invocation.rst b/doc/invocation.rst index c6125ecc5..4f4d81ac4 100644 --- a/doc/invocation.rst +++ b/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. diff --git a/sphinx/application.py b/sphinx/application.py index ceb7c32c7..57af69c5e 100644 --- a/sphinx/application.py +++ b/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 \ diff --git a/sphinx/cmdline.py b/sphinx/cmdline.py index e5ad3ab5b..2d7146c37 100644 --- a/sphinx/cmdline.py +++ b/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: diff --git a/sphinx/config.py b/sphinx/config.py index 4cca4b357..cb9955efe 100644 --- a/sphinx/config.py +++ b/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: diff --git a/sphinx/ext/todo.py b/sphinx/ext/todo.py index de5d2b9fe..253ae07d1 100644 --- a/sphinx/ext/todo.py +++ b/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) -