From 5ed44e0aa711ff1a1c9ac05ce1eadf4cac7fe266 Mon Sep 17 00:00:00 2001 From: Joel Nothman Date: Mon, 13 Nov 2017 23:36:44 +1100 Subject: [PATCH 1/3] FIX handling of parameter names ending '_' This issue results from #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 **. --- numpydoc/docscrape_sphinx.py | 12 +++++----- numpydoc/tests/test_docscrape.py | 38 ++++++++++++++++---------------- 2 files changed, 24 insertions(+), 26 deletions(-) diff --git a/numpydoc/docscrape_sphinx.py b/numpydoc/docscrape_sphinx.py index ff5be26c..af6f601e 100644 --- a/numpydoc/docscrape_sphinx.py +++ b/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 diff --git a/numpydoc/tests/test_docscrape.py b/numpydoc/tests/test_docscrape.py index 8fa3d23f..f91c3d29 100644 --- a/numpydoc/tests/test_docscrape.py +++ b/numpydoc/tests/test_docscrape.py @@ -477,24 +477,24 @@ 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). @@ -502,23 +502,23 @@ def test_sphinx_str(): 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 ` : float Test attribute - no_docstring : str + **no_docstring** : str But a description - no_docstring2 : str + **no_docstring2** : str :obj:`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. """) From 1fa4251cbe2ca9ec665891ff810e6fd1de1b510c Mon Sep 17 00:00:00 2001 From: Joel Nothman Date: Wed, 28 Mar 2018 17:33:33 +1100 Subject: [PATCH 2/3] Reference issue in comment --- numpydoc/docscrape_sphinx.py | 1 + 1 file changed, 1 insertion(+) diff --git a/numpydoc/docscrape_sphinx.py b/numpydoc/docscrape_sphinx.py index af6f601e..a25bcb5f 100644 --- a/numpydoc/docscrape_sphinx.py +++ b/numpydoc/docscrape_sphinx.py @@ -124,6 +124,7 @@ def _process_param(self, param, desc, fake_autosummary): param = param.strip() # XXX: If changing the following, please check the rendering when param # ends with '_', e.g. 'word_' + # See https://github.com/numpy/numpydoc/pull/144 display_param = '**%s**' % param if not fake_autosummary: From a4d94cd4e300ae0a1cf50da186087e5defcb8a6a Mon Sep 17 00:00:00 2001 From: Joel Nothman Date: Thu, 29 Mar 2018 11:56:34 +1100 Subject: [PATCH 3/3] Fix merge --- numpydoc/tests/test_docscrape.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/numpydoc/tests/test_docscrape.py b/numpydoc/tests/test_docscrape.py index ebb4769a..56f5f5a5 100644 --- a/numpydoc/tests/test_docscrape.py +++ b/numpydoc/tests/test_docscrape.py @@ -513,7 +513,7 @@ def test_sphinx_str(): This is not a real return value. It exists to test anonymous return values. - no_description + **no_description** .. :Other Parameters: