FIX handling of parameter names ending '_'

This issue results from numpy#107: the explicit bold styling was removed because Sphinx definition lists bolded the term by default. However, without ** surrounding param name, a name like word_ was being treated as a link. I also attempted to replace the _ with \_ but found that the backslashes showed in the HTML. Thus I have reverted to wrapping param names in **.

Author: jnothman

numpydoc/docscrape_sphinx.py

@@ -67,12 +67,8 @@ def _str_extended_summary(self):
         return self['Extended Summary'] + ['']
 
     def _str_returns(self, name='Returns'):
-        if self.use_blockquotes:
-            typed_fmt = '**%s** : %s'
-            untyped_fmt = '**%s**'
-        else:
-            typed_fmt = '%s : %s'
-            untyped_fmt = '%s'
+        typed_fmt = '**%s** : %s'
+        untyped_fmt = '**%s**'
 
         out = []
         if self[name]:
@@ -126,7 +122,9 @@ 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
+        # XXX: If changing the following, please check the rendering when param
+        # ends with '_', e.g. 'word_'
+        display_param = '**%s**' % param
 
         if not fake_autosummary:
             return display_param, desc

numpydoc/tests/test_docscrape.py

@@ -477,48 +477,48 @@ def test_sphinx_str():
 
 :Parameters:
 
-    mean : (N,) ndarray
+    **mean** : (N,) ndarray
         Mean of the N-dimensional distribution.
 
         .. math::
 
            (1+2+3)/3
 
-    cov : (N, N) ndarray
+    **cov** : (N, N) ndarray
         Covariance matrix of the distribution.
 
-    shape : tuple of ints
+    **shape** : tuple of ints
         Given a shape of, for example, (m,n,k), m*n*k samples are
         generated, and packed in an m-by-n-by-k arrangement.  Because
         each sample is N-dimensional, the output shape is (m,n,k,N).
 
 :Returns:
 
-    out : ndarray
+    **out** : ndarray
         The drawn samples, arranged according to `shape`.  If the
         shape given is (m,n,...), then the shape of `out` is is
         (m,n,...,N).
 
         In other words, each entry ``out[i,j,...,:]`` is an N-dimensional
         value drawn from the distribution.
 
-    list of str
+    **list of str**
         This is not a real return value.  It exists to test
         anonymous return values.
 
 :Other Parameters:
 
-    spam : parrot
+    **spam** : parrot
         A parrot off its mortal coil.
 
 :Raises:
 
-    RuntimeError
+    **RuntimeError**
         Some error
 
 :Warns:
 
-    RuntimeWarning
+    **RuntimeWarning**
         Some warning
 
 .. warning::
@@ -586,13 +586,13 @@ def test_sphinx_yields_str():
 
 :Yields:
 
-    a : int
+    **a** : int
         The number of apples.
 
-    b : int
+    **b** : int
         The number of bananas.
 
-    int
+    **int**
         The number of unknowns.
 """)
 
@@ -1119,10 +1119,10 @@ def no_period(self):
 
     :Parameters:
 
-        f : callable ``f(t, y, *f_args)``
+        **f** : callable ``f(t, y, *f_args)``
             Aaa.
 
-        jac : callable ``jac(t, y, *jac_args)``
+        **jac** : callable ``jac(t, y, *jac_args)``
             Bbb.
 
     .. rubric:: Examples
@@ -1131,10 +1131,10 @@ def no_period(self):
 
     :Attributes:
 
-        t : float
+        **t** : float
             Current time.
 
-        y : ndarray
+        **y** : ndarray
             Current variable values.
 
             * hello
@@ -1143,10 +1143,10 @@ def no_period(self):
         :obj:`an_attribute <an_attribute>` : float
             Test attribute
 
-        no_docstring : str
+        **no_docstring** : str
             But a description
 
-        no_docstring2 : str
+        **no_docstring2** : str
 
         :obj:`multiline_sentence <multiline_sentence>`
             This is a sentence.
@@ -1179,10 +1179,10 @@ def test_templated_sections():
 
     :Parameters:
 
-        f : callable ``f(t, y, *f_args)``
+        **f** : callable ``f(t, y, *f_args)``
             Aaa.
 
-        jac : callable ``jac(t, y, *jac_args)``
+        **jac** : callable ``jac(t, y, *jac_args)``
             Bbb.
 
     """)