merge stable into default

13 files changed, 92 insertions, 30 deletions

diff --git a/CHANGES b/CHANGES
index e8d72d06..58311eb4 100644
--- a/CHANGES
+++ b/CHANGES
@@ -1,5 +1,14 @@
-Release 1.2.1 (in development)
-==============================
+Release 1.3 (in development)
+============================
+
+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/config.rst b/doc/config.rst
index 70ccd26e..f57e9eff 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -118,7 +118,7 @@ General configuration
    in that case.
 
    .. deprecated:: 1.0
-      Use :confval:`exclude_patterns` instead.
+      Use :confval:`exclude_patterns` or :ref:`metadata` instead.
 
 .. confval:: exclude_trees
 
diff --git a/doc/invocation.rst b/doc/invocation.rst
index c6125ecc..4f4d81ac 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/doc/markup/toctree.rst b/doc/markup/toctree.rst
index 41c265f8..90666b72 100644
--- a/doc/markup/toctree.rst
+++ b/doc/markup/toctree.rst
@@ -141,8 +141,9 @@ tables of contents.  The ``toctree`` directive is the central element.
    In the end, all documents in the :term:`source directory` (or subdirectories)
    must occur in some ``toctree`` directive; Sphinx will emit a warning if it
    finds a file that is not included, because that means that this file will not
-   be reachable through standard navigation.  Use :confval:`exclude_patterns` to
-   explicitly exclude documents or directories from building.
+   be reachable through standard navigation.  Use :ref:`metadata` to remove the
+   warning, and :confval:`exclude_patterns` to explicitly exclude documents or
+   directories from building.
 
    The "master document" (selected by :confval:`master_doc`) is the "root" of
    the TOC tree hierarchy.  It can be used as the documentation's main page, or
diff --git a/sphinx/__init__.py b/sphinx/__init__.py
index d41d4424..f93e57a1 100644
--- a/sphinx/__init__.py
+++ b/sphinx/__init__.py
@@ -15,12 +15,12 @@
 import sys
 from os import path
 
-__version__  = '1.2+'
-__released__ = '1.2'  # used when Sphinx builds its own docs
+__version__  = '1.3a0'
+__released__ = '1.3a0'  # used when Sphinx builds its own docs
 # version info for better programmatic use
 # possible values for 3rd element: 'alpha', 'beta', 'rc', 'final'
 # 'final' has 0 as the last element
-version_info = (1, 2, 0, 'final', 0)
+version_info = (1, 3, 0, 'alpha', 0)
 
 package_dir = path.abspath(path.dirname(__file__))
 
diff --git a/sphinx/application.py b/sphinx/application.py
index ceb7c32c..57af69c5 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 e5ad3ab5..2d7146c3 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 4cca4b35..9ea2226e 100644
--- a/sphinx/config.py
+++ b/sphinx/config.py
@@ -214,8 +214,11 @@ class Config(object):
         self.overrides = overrides
         self.values = Config.config_values.copy()
         config = {}
-        if "extensions" in overrides:
-            config["extensions"] = overrides["extensions"]
+        if 'extensions' in overrides:
+            if isinstance(overrides['extensions'], (str, unicode)):
+                config['extensions'] = overrides.pop('extensions').split(',')
+            else:
+                config['extensions'] = overrides.pop('extensions')
         if dirname is not None:
             config_file = path.join(dirname, filename)
             config['__file__'] = config_file
@@ -248,12 +251,36 @@ 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(value, (str, unicode)):
+                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 defvalue is not None and not isinstance(defvalue, (str, unicode)):
+                    warn('cannot override config setting %r with unsupported type, '
+                         'ignoring' % valname)
+                else:
+                    config[valname] = value
             else:
                 config[valname] = value
         for name in config:
diff --git a/sphinx/domains/python.py b/sphinx/domains/python.py
index 0c08b60b..63d388c8 100644
--- a/sphinx/domains/python.py
+++ b/sphinx/domains/python.py
@@ -81,6 +81,23 @@ def _pseudo_parse_arglist(signode, arglist):
         signode += paramlist
 
 
+# This override allows our inline type specifiers to behave like :class: link
+# when it comes to handling "." and "~" prefixes.
+class PyTypedField(TypedField):
+    def make_xref(self, rolename, domain, target, innernode=nodes.emphasis):
+        result = super(PyTypedField, self).make_xref(rolename, domain, target,
+                                                     innernode)
+        if target.startswith('.'):
+            result['reftarget'] = target[1:]
+            result['refspecific'] = True
+            result[0][0] = nodes.Text(target[1:])
+        if target.startswith('~'):
+            result['reftarget'] = target[1:]
+            title = target.split('.')[-1]
+            result[0][0] = nodes.Text(title)
+        return result
+
+
 class PyObject(ObjectDescription):
     """
     Description of a general Python object.
@@ -92,7 +109,7 @@ class PyObject(ObjectDescription):
     }
 
     doc_field_types = [
-        TypedField('parameter', label=l_('Parameters'),
+        PyTypedField('parameter', label=l_('Parameters'),
                    names=('param', 'parameter', 'arg', 'argument',
                           'keyword', 'kwarg', 'kwparam'),
                    typerolename='obj', typenames=('paramtype', 'type'),
diff --git a/sphinx/ext/todo.py b/sphinx/ext/todo.py
index de5d2b9f..253ae07d 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)
-
diff --git a/tests/root/objects.txt b/tests/root/objects.txt
index 57e82212..819c5dff 100644
--- a/tests/root/objects.txt
+++ b/tests/root/objects.txt
@@ -101,6 +101,7 @@ Referring to :func:`nothing <>`.
    :type hour: DuplicateType
    :param hour: Duplicate param.  Should not lead to crashes.
    :type hour: DuplicateType
+   :param .Cls extcls: A class from another module.
 
 
 C items
diff --git a/tests/test_config.py b/tests/test_config.py
index 4d3d51b0..ea6f3ba4 100644
--- a/tests/test_config.py
+++ b/tests/test_config.py
@@ -19,7 +19,8 @@ from sphinx.util.pycompat import b
 
 
 @with_app(confoverrides={'master_doc': 'master', 'nonexisting_value': 'True',
-                         'latex_elements.docclass': 'scrartcl'})
+                         'latex_elements.docclass': 'scrartcl',
+                         'modindex_common_prefix': 'path1,path2'})
 def test_core_config(app):
     cfg = app.config
 
@@ -31,6 +32,7 @@ def test_core_config(app):
     # overrides
     assert cfg.master_doc == 'master'
     assert cfg.latex_elements['docclass'] == 'scrartcl'
+    assert cfg.modindex_common_prefix == ['path1', 'path2']
 
     # simple default values
     assert 'locale_dirs' not in cfg.__dict__
@@ -92,7 +94,7 @@ def test_errors_warnings(dir):
     write_file(dir / 'conf.py', u'# -*- coding: utf-8\n\n'
                u'project = u"Jägermeister"\n', 'utf-8')
     cfg = Config(dir, 'conf.py', {}, None)
-    cfg.init_values()
+    cfg.init_values(lambda warning: 1/0)
     assert cfg.project == u'Jägermeister'
 
     # test the warning for bytestrings with non-ascii content
@@ -122,5 +124,5 @@ def test_config_eol(tmpdir):
     for eol in ('\n', '\r\n'):
         configfile.write_bytes(b('project = "spam"' + eol))
         cfg = Config(tmpdir, 'conf.py', {}, None)
-        cfg.init_values()
+        cfg.init_values(lambda warning: 1/0)
         assert cfg.project == u'spam'
diff --git a/tests/test_intersphinx.py b/tests/test_intersphinx.py
index a8679e7e..8ce02cc1 100644
--- a/tests/test_intersphinx.py
+++ b/tests/test_intersphinx.py
@@ -81,7 +81,7 @@ def test_read_inventory_v2():
            '/util/glossary.html#term-a-term'
 
 
-@with_app(confoverrides={'extensions': 'sphinx.ext.intersphinx'})
+@with_app()
 @with_tempdir
 def test_missing_reference(tempdir, app):
     inv_file = tempdir / 'inventory'
@@ -157,7 +157,7 @@ def test_missing_reference(tempdir, app):
     assert contnode[0].astext() == 'py3k:unknown'
 
 
-@with_app(confoverrides={'extensions': 'sphinx.ext.intersphinx'})
+@with_app()
 @with_tempdir
 def test_load_mappings_warnings(tempdir, app):
     """