From 8fa009891988304b0729e47b251367c737b885d5 Mon Sep 17 00:00:00 2001 From: Hassan Kibirige Date: Tue, 16 Jan 2018 23:35:52 -0600 Subject: [PATCH 1/3] Escape the * in *args and **kwargs Prevents sphinx from complaining `WARNING: Inline strong start-string without end-string.` Credit: Solution taken directly from sphinx.ext.napoleon --- numpydoc/docscrape.py | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/numpydoc/docscrape.py b/numpydoc/docscrape.py index 598b4438..e3d800a6 100644 --- a/numpydoc/docscrape.py +++ b/numpydoc/docscrape.py @@ -199,6 +199,14 @@ def _read_to_next_section(self): return section + def _escape_args_and_kwargs(self, name): + if name[:2] == '**': + return r'\*\*' + name[2:] + elif name[:1] == '*': + return r'\*' + name[1:] + else: + return name + def _read_sections(self): while not self._doc.eof(): data = self._read_to_next_section() @@ -221,6 +229,7 @@ def _parse_param_list(self, content): else: arg_name, arg_type = header, '' + arg_name = self._escape_args_and_kwargs(arg_name) desc = r.read_to_next_unindented_line() desc = dedent_lines(desc) desc = strip_blank_lines(desc) From 050a6e6d8e21882b6349ce8685c3d364b5bfbd8d Mon Sep 17 00:00:00 2001 From: Hassan Kibirige Date: Tue, 16 Jan 2018 23:58:59 -0600 Subject: [PATCH 2/3] Move arg and kwargs escaping to docscrape_sphinx --- numpydoc/docscrape.py | 9 --------- numpydoc/docscrape_sphinx.py | 10 +++++++++- 2 files changed, 9 insertions(+), 10 deletions(-) diff --git a/numpydoc/docscrape.py b/numpydoc/docscrape.py index e3d800a6..598b4438 100644 --- a/numpydoc/docscrape.py +++ b/numpydoc/docscrape.py @@ -199,14 +199,6 @@ def _read_to_next_section(self): return section - def _escape_args_and_kwargs(self, name): - if name[:2] == '**': - return r'\*\*' + name[2:] - elif name[:1] == '*': - return r'\*' + name[1:] - else: - return name - def _read_sections(self): while not self._doc.eof(): data = self._read_to_next_section() @@ -229,7 +221,6 @@ def _parse_param_list(self, content): else: arg_name, arg_type = header, '' - arg_name = self._escape_args_and_kwargs(arg_name) desc = r.read_to_next_unindented_line() desc = dedent_lines(desc) desc = strip_blank_lines(desc) diff --git a/numpydoc/docscrape_sphinx.py b/numpydoc/docscrape_sphinx.py index 8031aabd..31826e77 100644 --- a/numpydoc/docscrape_sphinx.py +++ b/numpydoc/docscrape_sphinx.py @@ -88,6 +88,14 @@ def _str_returns(self, name='Returns'): out += [''] return out + def _escape_args_and_kwargs(self, name): + if name[:2] == '**': + return r'\*\*' + name[2:] + elif name[:1] == '*': + return r'\*' + name[1:] + else: + return name + def _process_param(self, param, desc, fake_autosummary): """Determine how to display a parameter @@ -122,7 +130,7 @@ def _process_param(self, param, desc, fake_autosummary): complicated to incorporate autosummary's signature mangling, as it relies on Sphinx's plugin mechanism. """ - param = param.strip() + param = self._escape_args_and_kwargs(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 From 5a311f35927abdbee01d2a079ea31cb766bf9fdb Mon Sep 17 00:00:00 2001 From: Hassan Kibirige Date: Sun, 1 Apr 2018 22:13:17 +0300 Subject: [PATCH 3/3] Add tests --- numpydoc/docscrape_sphinx.py | 1 + numpydoc/tests/test_docscrape.py | 26 ++++++++++++++++++++++++++ 2 files changed, 27 insertions(+) diff --git a/numpydoc/docscrape_sphinx.py b/numpydoc/docscrape_sphinx.py index 31826e77..257a61e4 100644 --- a/numpydoc/docscrape_sphinx.py +++ b/numpydoc/docscrape_sphinx.py @@ -131,6 +131,7 @@ def _process_param(self, param, desc, fake_autosummary): relies on Sphinx's plugin mechanism. """ param = self._escape_args_and_kwargs(param.strip()) + # 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 diff --git a/numpydoc/tests/test_docscrape.py b/numpydoc/tests/test_docscrape.py index 7b207abd..227ee643 100644 --- a/numpydoc/tests/test_docscrape.py +++ b/numpydoc/tests/test_docscrape.py @@ -1226,6 +1226,32 @@ class Dummy: assert "test attribute" in str(doc) +def test_args_and_kwargs(): + cfg = dict() + doc = SphinxDocString(""" + Parameters + ---------- + param1 : int + First parameter + *args : tuple + Arguments + **kwargs : dict + Keyword arguments + """, config=cfg) + line_by_line_compare(str(doc), """ +:Parameters: + + **param1** : int + First parameter + + **\*args** : tuple + Arguments + + **\*\*kwargs** : dict + Keyword arguments + """) + + if __name__ == "__main__": import nose nose.run()