Closes #1623: Return types specified with ``:rtype:`` are now turned into links if possible.

2 files changed, 41 insertions, 21 deletions

diff --git a/sphinx/domains/python.py b/sphinx/domains/python.py
index 4e08eba9..692010c1 100644
--- a/sphinx/domains/python.py
+++ b/sphinx/domains/python.py
@@ -84,13 +84,14 @@ def _pseudo_parse_arglist(signode, arglist):
 
 # 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)
+class PyXrefMixin(object):
+    def make_xref(self, rolename, domain, target, innernode=nodes.emphasis,
+                  contnode=None):
+        result = super(PyXrefMixin, self).make_xref(rolename, domain, target,
+                                                    innernode, contnode)
+        result['refspecific'] = True
         if target.startswith('.'):
             result['reftarget'] = target[1:]
-            result['refspecific'] = True
             result[0][0] = nodes.Text(target[1:])
         if target.startswith('~'):
             result['reftarget'] = target[1:]
@@ -99,6 +100,14 @@ class PyTypedField(TypedField):
         return result
 
 
+class PyField(PyXrefMixin, Field):
+    pass
+
+
+class PyTypedField(PyXrefMixin, TypedField):
+    pass
+
+
 class PyObject(ObjectDescription):
     """
     Description of a general Python object.
@@ -111,21 +120,21 @@ class PyObject(ObjectDescription):
 
     doc_field_types = [
         PyTypedField('parameter', label=l_('Parameters'),
-                   names=('param', 'parameter', 'arg', 'argument',
-                          'keyword', 'kwarg', 'kwparam'),
-                   typerolename='obj', typenames=('paramtype', 'type'),
-                   can_collapse=True),
-        TypedField('variable', label=l_('Variables'), rolename='obj',
-                   names=('var', 'ivar', 'cvar'),
-                   typerolename='obj', typenames=('vartype',),
-                   can_collapse=True),
+                     names=('param', 'parameter', 'arg', 'argument',
+                            'keyword', 'kwarg', 'kwparam'),
+                     typerolename='obj', typenames=('paramtype', 'type'),
+                     can_collapse=True),
+        PyTypedField('variable', label=l_('Variables'), rolename='obj',
+                     names=('var', 'ivar', 'cvar'),
+                     typerolename='obj', typenames=('vartype',),
+                     can_collapse=True),
         GroupedField('exceptions', label=l_('Raises'), rolename='exc',
                      names=('raises', 'raise', 'exception', 'except'),
                      can_collapse=True),
         Field('returnvalue', label=l_('Returns'), has_arg=False,
               names=('returns', 'return')),
-        Field('returntype', label=l_('Return type'), has_arg=False,
-              names=('rtype',)),
+        PyField('returntype', label=l_('Return type'), has_arg=False,
+                names=('rtype',), bodyrolename='obj'),
     ]
 
     def get_signature_prefix(self, sig):
diff --git a/sphinx/util/docfields.py b/sphinx/util/docfields.py
index abb73288..46f89430 100644
--- a/sphinx/util/docfields.py
+++ b/sphinx/util/docfields.py
@@ -29,11 +29,13 @@ def _is_single_paragraph(node):
 
 
 class Field(object):
-    """
-    A doc field that is never grouped.  It can have an argument or not, the
+    """A doc field that is never grouped.  It can have an argument or not, the
     argument can be linked using a specified *rolename*.  Field should be used
     for doc fields that usually don't occur more than once.
 
+    The body can be linked using a specified *bodyrolename* if the content is
+    just a single inline or text node.
+
     Example::
 
        :returns: description of the return value
@@ -42,19 +44,22 @@ class Field(object):
     is_grouped = False
     is_typed = False
 
-    def __init__(self, name, names=(), label=None, has_arg=True, rolename=None):
+    def __init__(self, name, names=(), label=None, has_arg=True, rolename=None,
+                 bodyrolename=None):
         self.name = name
         self.names = names
         self.label = label
         self.has_arg = has_arg
         self.rolename = rolename
+        self.bodyrolename = bodyrolename
 
-    def make_xref(self, rolename, domain, target, innernode=nodes.emphasis):
+    def make_xref(self, rolename, domain, target, innernode=nodes.emphasis,
+                  contnode=None):
         if not rolename:
-            return innernode(target, target)
+            return contnode or innernode(target, target)
         refnode = addnodes.pending_xref('', refdomain=domain, refexplicit=False,
                                         reftype=rolename, reftarget=target)
-        refnode += innernode(target, target)
+        refnode += contnode or innernode(target, target)
         return refnode
 
     def make_entry(self, fieldarg, content):
@@ -67,6 +72,12 @@ class Field(object):
             fieldname += nodes.Text(' ')
             fieldname += self.make_xref(self.rolename, domain,
                                         fieldarg, nodes.Text)
+        if len(content) == 1 and (
+                isinstance(content[0], nodes.Text) or
+                (isinstance(content[0], nodes.inline) and len(content[0]) == 1
+                 and isinstance(content[0][0], nodes.Text))):
+            content = [self.make_xref(self.bodyrolename, domain,
+                                      content[0].astext(), contnode=content[0])]
         fieldbody = nodes.field_body('', nodes.paragraph('', '', *content))
         return nodes.field('', fieldname, fieldbody)