Change the way to handle return annotations a bit.

sphinx/addnodes.py

@@ -23,8 +23,12 @@ class desc(nodes.Admonition, nodes.Element): pass
 class desc_addname(nodes.Part, nodes.Inline, nodes.TextElement): pass
 # compatibility alias
 desc_classname = desc_addname
-# return type (C); object type, e.g. -> annotation (Python)
+# return type (C); object type
 class desc_type(nodes.Part, nodes.Inline, nodes.TextElement): pass
+# -> annotation (Python)
+class desc_returns(desc_type):
+    def astext(self):
+        return ' -> ' + nodes.TextElement.astext(self)
 # main name of object
 class desc_name(nodes.Part, nodes.Inline, nodes.TextElement): pass
 # argument list
@@ -90,7 +94,8 @@ class meta(nodes.Special, nodes.PreBibliographic, nodes.Element): pass
 
 # make them known to docutils. this is needed, because the HTML writer
 # will choke at some point if these are not added
-nodes._add_node_class_names("""index desc desc_content desc_signature desc_type
+nodes._add_node_class_names("""index desc desc_content desc_signature
+      desc_type desc_returns
       desc_addname desc_name desc_parameterlist desc_parameter desc_optional
       centered versionmodified seealso productionlist production toctree
       pending_xref compact_paragraph highlightlang literal_emphasis

sphinx/directives/desc.py

@@ -209,8 +209,9 @@ def handle_doc_fields(node, env):
 py_sig_re = re.compile(
     r'''^ ([\w.]*\.)?            # class name(s)
           (\w+)  \s*             # thing name
-          (?: \((.*)\)           # optional arguments
-          (\s* -> \s* .*)? )? $  # optional return annotation
+          (?: \((.*)\)           # optional: arguments
+           (?:\s* -> \s* (.*))?  #           return annotation
+          )? $                   # and nothing more
           ''', re.VERBOSE)
 
 py_paramlist_re = re.compile(r'([\[\],])')  # split at '[', ']' and ','
@@ -229,9 +230,6 @@ def parse_py_signature(signode, sig, desctype, module, env):
         raise ValueError
     classname, name, arglist, retann = m.groups()
 
-    if retann:
-        retann = u' \N{RIGHTWARDS ARROW} ' + retann.strip()[2:]
-
     if env.currclass:
         add_module = False
         if classname and classname.startswith(env.currclass):
@@ -267,7 +265,7 @@ def parse_py_signature(signode, sig, desctype, module, env):
             # for callables, add an empty parameter list
             signode += addnodes.desc_parameterlist()
         if retann:
-            signode += addnodes.desc_type(retann, retann)
+            signode += addnodes.desc_returns(retann, retann)
         return fullname, classname
     signode += addnodes.desc_parameterlist()
 
@@ -290,7 +288,7 @@ def parse_py_signature(signode, sig, desctype, module, env):
     if len(stack) != 1:
         raise ValueError
     if retann:
-        signode += addnodes.desc_type(retann, retann)
+        signode += addnodes.desc_returns(retann, retann)
     return fullname, classname
 
 

sphinx/ext/autodoc.py

@@ -36,8 +36,9 @@ py_ext_sig_re = re.compile(
     r'''^ ([\w.]+::)?            # explicit module name
           ([\w.]+\.)?            # module and/or class name(s)
           (\w+)  \s*             # thing name
-          (?: \((.*)\)           # optional arguments
-          (\s* -> \s* .*)? )? $  # optional return annotation
+          (?: \((.*)\)           # optional: arguments
+           (?:\s* -> \s* (.*))?  #           return annotation
+          )? $                   # and nothing more
           ''', re.VERBOSE)
 
 
@@ -391,7 +392,7 @@ class RstGenerator(object):
             args, retann = result
 
         if args is not None:
-            return '%s%s' % (args, retann or '')
+            return '%s%s' % (args, retann and (' -> %s' % retann) or '')
         elif err:
             # re-raise the error for perusal of the handler in generate()
             raise RuntimeError(err)

sphinx/writers/html.py

@@ -90,6 +90,11 @@ class HTMLTranslator(BaseTranslator):
     def depart_desc_type(self, node):
         pass
 
+    def visit_desc_returns(self, node):
+        self.body.append(' → ')
+    def depart_desc_returns(self, node):
+        pass
+
     def visit_desc_name(self, node):
         self.body.append(self.starttag(node, 'tt', '', CLASS='descname'))
     def depart_desc_name(self, node):

sphinx/writers/latex.py

@@ -112,7 +112,8 @@ class Table(object):
 class Desc(object):
     def __init__(self, node):
         self.env = LaTeXTranslator.desc_map.get(node['desctype'], 'describe')
-        self.type = self.cls = self.name = self.params = self.annotation = ''
+        self.type = self.cls = self.name = self.params = \
+                    self.annotation = self.returns = ''
         self.count = 0
 
 
@@ -477,6 +478,14 @@ class LaTeXTranslator(nodes.NodeVisitor):
             self.descstack[-1].type = self.encode(node.astext().strip())
         raise nodes.SkipNode
 
+    def visit_desc_returns(self, node):
+        d = self.descstack[-1]
+        if d.env == 'describe':
+            d.name += ' $\\rightarrow$ ' + self.encode(node.astext())
+        else:
+            self.descstack[-1].returns = self.encode(node.astext().strip())
+        raise nodes.SkipNode
+
     def visit_desc_name(self, node):
         d = self.descstack[-1]
         if d.env == 'describe':

sphinx/writers/text.py

@@ -195,6 +195,11 @@ class TextTranslator(nodes.NodeVisitor):
     def depart_desc_type(self, node):
         pass
 
+    def visit_desc_returns(self, node):
+        self.add_text(' -> ')
+    def depart_desc_returns(self, node):
+        pass
+
     def visit_desc_parameterlist(self, node):
         self.add_text('(')
         self.first_param = 1