merge stable into default

6 files changed, 34 insertions, 9 deletions

diff --git a/CHANGES b/CHANGES
index 6959cb9d..34e7158e 100644
--- a/CHANGES
+++ b/CHANGES
@@ -1,5 +1,11 @@
-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.
 
 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/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/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/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