From 061d9c205fc6bd2fa820e09d04facfc81ce5e7c1 Mon Sep 17 00:00:00 2001
From: Georg Brandl <georg@python.org>
Date: Wed, 18 Jun 2008 18:34:18 +0000
Subject: [PATCH] Support -> return type annotations.

---
 CHANGES                   |  3 +++
 sphinx/directives/desc.py | 15 ++++++++++-----
 sphinx/ext/autodoc.py     |  4 +++-
 sphinx/latexwriter.py     |  1 +
 4 files changed, 17 insertions(+), 6 deletions(-)

diff --git a/CHANGES b/CHANGES
index 8b9cfa176..998baba75 100644
--- a/CHANGES
+++ b/CHANGES
@@ -57,6 +57,9 @@ New features added
 
 * The new TextBuilder creates plain-text output.
 
+* Python 3-style signatures, giving a return annotation via ``->``,
+  are now supported.
+
 * Extensions:
     
   - The `autodoc` extension accepts signatures for functions, methods
diff --git a/sphinx/directives/desc.py b/sphinx/directives/desc.py
index 30aab841d..60498eb9a 100644
--- a/sphinx/directives/desc.py
+++ b/sphinx/directives/desc.py
@@ -75,10 +75,12 @@ def desc_index_text(desctype, module, name):
 
 # ------ functions to parse a Python or C signature and create desc_* nodes.
 
-py_sig_re = re.compile(r'''^([\w.]*\.)?        # class names
-                           (\w+)  \s*          # thing name
-                           (?: \((.*)\) )? $   # optionally arguments
-                        ''', re.VERBOSE)
+py_sig_re = re.compile(
+    r'''^ ([\w.]*\.)?            # class name(s)
+          (\w+)  \s*             # thing name
+          (?: \((.*)\)           # optional arguments
+          (\s* -> \s* .*)? )? $  # optional return annotation
+          ''', re.VERBOSE)
 
 py_paramlist_re = re.compile(r'([\[\],])')  # split at '[', ']' and ','
 
@@ -94,7 +96,7 @@ def parse_py_signature(signode, sig, desctype, module, env):
     m = py_sig_re.match(sig)
     if m is None:
         raise ValueError
-    classname, name, arglist = m.groups()
+    classname, name, arglist, retann = m.groups()
 
     if env.currclass:
         add_module = False
@@ -148,6 +150,9 @@ def parse_py_signature(signode, sig, desctype, module, env):
             stack[-1] += addnodes.desc_parameter(token, token)
     if len(stack) != 1:
         raise ValueError
+    if retann:
+        retann = u' \N{RIGHTWARDS ARROW} ' + retann.strip()[2:]
+        signode += addnodes.desc_type(retann, retann)
     return fullname, classname
 
 
diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py
index 9cf794f7d..49180e611 100644
--- a/sphinx/ext/autodoc.py
+++ b/sphinx/ext/autodoc.py
@@ -198,7 +198,7 @@ def generate_rst(what, name, members, options, add_content, document, lineno,
     # first, parse the definition -- auto directives for classes and functions
     # can contain a signature which is then used instead of an autogenerated one
     try:
-        path, base, signature = py_sig_re.match(name).groups()
+        path, base, signature, retann = py_sig_re.match(name).groups()
     except:
         warning = document.reporter.warning(
             'invalid signature for auto%s (%r)' % (what, name), line=lineno)
@@ -290,6 +290,8 @@ def generate_rst(what, name, members, options, add_content, document, lineno,
     if signature is not None:
         # signature given explicitly -- the parentheses were stripped by the regex
         args = '(%s)' % signature
+        if retann:
+            args += retann
     else:
         try:
             args = format_signature(what, todoc)
diff --git a/sphinx/latexwriter.py b/sphinx/latexwriter.py
index c499ed73c..ae92f3be7 100644
--- a/sphinx/latexwriter.py
+++ b/sphinx/latexwriter.py
@@ -979,6 +979,7 @@ class LaTeXTranslator(nodes.NodeVisitor):
         (u">", ur"\textgreater{}"),
         (u"^", ur"\textasciicircum{}"),
         (u"\x00", ur"\textbackslash{}"),
+        (u"\N{RIGHTWARDS ARROW}", ur"$\rightarrow$"),
     ]
 
     def encode(self, text):