From a0dc1d997008e3a2dc35789d3d9a9f9c0708ec17 Mon Sep 17 00:00:00 2001
From: Joel Nothman <joel.nothman@gmail.com>
Date: Wed, 10 Jan 2018 16:06:47 +1100
Subject: [PATCH] FIX Handle param names ending in underscore

---
 doc/example.py                   |  4 ++--
 numpydoc/docscrape_sphinx.py     | 14 +++++++++++++-
 numpydoc/tests/test_docscrape.py | 14 +++++++-------
 3 files changed, 22 insertions(+), 10 deletions(-)

diff --git a/doc/example.py b/doc/example.py
index c55d64df..ea0ee73c 100644
--- a/doc/example.py
+++ b/doc/example.py
@@ -56,8 +56,8 @@ def foo(var1, var2, long_var_name='hi'):
 
     Returns
     -------
-    type
-        Explanation of anonymous return value of type ``type``.
+    type_
+        Explanation of anonymous return value of type ``type_``.
     describe : type
         Explanation of return value named `describe`.
     out : type
diff --git a/numpydoc/docscrape_sphinx.py b/numpydoc/docscrape_sphinx.py
index 640efa7b..38461dd2 100644
--- a/numpydoc/docscrape_sphinx.py
+++ b/numpydoc/docscrape_sphinx.py
@@ -79,6 +79,7 @@ def _str_returns(self, name='Returns'):
             out += self._str_field_list(name)
             out += ['']
             for param, param_type, desc in self[name]:
+                param = self._escape_param(param)
                 if param_type:
                     out += self._str_indent([typed_fmt % (param.strip(),
                                                           param_type)])
@@ -91,6 +92,16 @@ def _str_returns(self, name='Returns'):
                 out += ['']
         return out
 
+    def _escape_param(self, param):
+        """Escape a parameter name for reST
+
+        Currently only handles param names with final underscore
+        """
+        param = param.strip()
+        if param[-1:] == '_':
+            param = param[:-1] + '\\_'
+        return param
+
     def _process_param(self, param, desc, fake_autosummary):
         """Determine how to display a parameter
 
@@ -126,7 +137,8 @@ def _process_param(self, param, desc, fake_autosummary):
         relies on Sphinx's plugin mechanism.
         """
         param = param.strip()
-        display_param = ('**%s**' if self.use_blockquotes else '%s') % param
+        display_param = ('**%s**' if self.use_blockquotes
+                         else '%s') % self._escape_param(param)
 
         if not fake_autosummary:
             return display_param, desc
diff --git a/numpydoc/tests/test_docscrape.py b/numpydoc/tests/test_docscrape.py
index fa3f700f..60638337 100644
--- a/numpydoc/tests/test_docscrape.py
+++ b/numpydoc/tests/test_docscrape.py
@@ -28,7 +28,7 @@
 
 
 doc_txt = '''\
-  numpy.multivariate_normal(mean, cov, shape=None, spam=None)
+  numpy.multivariate_normal(mean, cov, shape=None, spam_=None)
 
   Draw values from a multivariate normal distribution with specified
   mean and covariance.
@@ -67,7 +67,7 @@
 
   Other Parameters
   ----------------
-  spam : parrot
+  spam_ : parrot
       A parrot off its mortal coil.
 
   Raises
@@ -153,7 +153,7 @@
 
 def test_signature():
     assert doc['Signature'].startswith('numpy.multivariate_normal(')
-    assert doc['Signature'].endswith('spam=None)')
+    assert doc['Signature'].endswith('spam_=None)')
 
 
 def test_summary():
@@ -177,7 +177,7 @@ def test_parameters():
 
 def test_other_parameters():
     assert_equal(len(doc['Other Parameters']), 1)
-    assert_equal([n for n,_,_ in doc['Other Parameters']], ['spam'])
+    assert_equal([n for n,_,_ in doc['Other Parameters']], ['spam_'])
     arg, arg_type, desc = doc['Other Parameters'][0]
     assert_equal(arg_type, 'parrot')
     assert desc[0].startswith('A parrot off its mortal coil')
@@ -338,7 +338,7 @@ def test_str():
     # This should be handled automatically, and so, one thing this test does
     # is to make sure that See Also precedes Notes in the output.
     line_by_line_compare(str(doc),
-"""numpy.multivariate_normal(mean, cov, shape=None, spam=None)
+"""numpy.multivariate_normal(mean, cov, shape=None, spam_=None)
 
 Draw values from a multivariate normal distribution with specified
 mean and covariance.
@@ -376,7 +376,7 @@ def test_str():
 
 Other Parameters
 ----------------
-spam : parrot
+spam_ : parrot
     A parrot off its mortal coil.
 
 Raises
@@ -508,7 +508,7 @@ def test_sphinx_str():
 
 :Other Parameters:
 
-    spam : parrot
+    spam\\_ : parrot
         A parrot off its mortal coil.
 
 :Raises: