From 362853597a8de1c1ab5bcafda7345432e47c5c6d Mon Sep 17 00:00:00 2001 From: Joel Nothman Date: Tue, 14 Nov 2017 12:19:07 +1100 Subject: [PATCH 1/3] WIP --- numpydoc/docscrape_sphinx.py | 27 ++++++++++++++++++++++----- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/numpydoc/docscrape_sphinx.py b/numpydoc/docscrape_sphinx.py index ff5be26c..0c3783f5 100644 --- a/numpydoc/docscrape_sphinx.py +++ b/numpydoc/docscrape_sphinx.py @@ -24,6 +24,10 @@ IMPORT_MATPLOTLIB_RE = r'\b(import +matplotlib|from +matplotlib +import)\b' +def _name_to_class(name, infix=''): + return 'numpydoc-%s%s' % (infix, re.sub(r'\W', '-', name.lower())) + + class SphinxDocString(NumpyDocString): def __init__(self, docstring, config={}): NumpyDocString.__init__(self, docstring, config=config) @@ -42,10 +46,14 @@ def load_config(self, config): # string conversion routines def _str_header(self, name, symbol='`'): - return ['.. rubric:: ' + name, ''] + return self._str_heading_classes(name) + ['.. rubric:: ' + name, ''] def _str_field_list(self, name): - return [':' + name + ':'] + return self._str_heading_classes(name) + [':' + name + ':'] + + def _str_heading_classes(self, name): + return ['.. rst-class:: numpydoc-heading %s' % + _name_to_class(name, 'heading-'), ''] def _str_indent(self, doc, indent=4): out = [] @@ -53,6 +61,11 @@ def _str_indent(self, doc, indent=4): out += [' '*indent + line] return out + def _in_container(self, content, name): + return (['.. rst-class:: numpydoc-section %s' % _name_to_class(name), + ''] + + self._str_indent(content, 4)) + def _str_signature(self): return [''] if self['Signature']: @@ -190,7 +203,9 @@ def _str_param_list(self, name, fake_autosummary=False): out = [] if self[name]: out += self._str_field_list(name) - out += [''] + out += ['', + '.. rst-class:: numpydoc-section %s' % _name_to_class(name), + ''] for param, param_type, desc in self[name]: display_param, desc = self._process_param(param, desc, fake_autosummary) @@ -224,7 +239,6 @@ def _str_member_list(self, name): """ out = [] if self[name]: - out += ['.. rubric:: %s' % name, ''] prefix = getattr(self, '_name', '') if prefix: @@ -266,6 +280,9 @@ def _str_member_list(self, name): out += [fmt % ("**" + param.strip() + "**", desc)] out += [hdr] out += [''] + + out = (self._str_header(name) + + self._in_container(out, name)) return out def _str_section(self, name): @@ -273,7 +290,7 @@ def _str_section(self, name): if self[name]: out += self._str_header(name) content = textwrap.dedent("\n".join(self[name])).split("\n") - out += content + out += self._in_container(content, name) out += [''] return out From 2c0020daea97c5a8bc320ea4e5e9ef943d29a907 Mon Sep 17 00:00:00 2001 From: Joel Nothman Date: Wed, 15 Nov 2017 18:32:30 +1100 Subject: [PATCH 2/3] Fix wrapping in classes --- numpydoc/docscrape_sphinx.py | 46 +++++++++++++++--------------------- 1 file changed, 19 insertions(+), 27 deletions(-) diff --git a/numpydoc/docscrape_sphinx.py b/numpydoc/docscrape_sphinx.py index 0c3783f5..84dec5b5 100644 --- a/numpydoc/docscrape_sphinx.py +++ b/numpydoc/docscrape_sphinx.py @@ -46,14 +46,10 @@ def load_config(self, config): # string conversion routines def _str_header(self, name, symbol='`'): - return self._str_heading_classes(name) + ['.. rubric:: ' + name, ''] + return ['.. rubric:: ' + name, ''] def _str_field_list(self, name): - return self._str_heading_classes(name) + [':' + name + ':'] - - def _str_heading_classes(self, name): - return ['.. rst-class:: numpydoc-heading %s' % - _name_to_class(name, 'heading-'), ''] + return [':' + name + ':'] def _str_indent(self, doc, indent=4): out = [] @@ -61,10 +57,9 @@ def _str_indent(self, doc, indent=4): out += [' '*indent + line] return out - def _in_container(self, content, name): - return (['.. rst-class:: numpydoc-section %s' % _name_to_class(name), - ''] + - self._str_indent(content, 4)) + def _wrap_section(self, content, name, directive='rst-class'): + return (['.. %s:: numpydoc-section %s' % (directive, _name_to_class(name)), + ''] + self._str_indent(content)) def _str_signature(self): return [''] @@ -89,19 +84,19 @@ def _str_returns(self, name='Returns'): out = [] if self[name]: - out += self._str_field_list(name) - out += [''] for param, param_type, desc in self[name]: if param_type: - out += self._str_indent([typed_fmt % (param.strip(), - param_type)]) + out += [typed_fmt % (param.strip(), param_type)] else: - out += self._str_indent([untyped_fmt % param.strip()]) + out += [untyped_fmt % param.strip()] if desc: if self.use_blockquotes: out += [''] - out += self._str_indent(desc, 8) + out += self._str_indent(desc) out += [''] + + out = (self._str_field_list(name) + [''] + + self._str_indent(self._wrap_section(out, name))) return out def _process_param(self, param, desc, fake_autosummary): @@ -202,25 +197,23 @@ def _str_param_list(self, name, fake_autosummary=False): """ out = [] if self[name]: - out += self._str_field_list(name) - out += ['', - '.. rst-class:: numpydoc-section %s' % _name_to_class(name), - ''] for param, param_type, desc in self[name]: display_param, desc = self._process_param(param, desc, fake_autosummary) if param_type: - out += self._str_indent(['%s : %s' % (display_param, - param_type)]) + out += ['%s : %s' % (display_param, param_type)] else: - out += self._str_indent([display_param]) + out += [display_param] if desc: if self.use_blockquotes: out += [''] - out += self._str_indent(desc, 8) + out += self._str_indent(desc) out += [''] + out = (self._str_field_list(name) + [''] + + self._str_indent(self._wrap_section(out, name))) + return out @property @@ -281,8 +274,7 @@ def _str_member_list(self, name): out += [hdr] out += [''] - out = (self._str_header(name) + - self._in_container(out, name)) + out = self._str_header(name) + self._wrap_section(out, name) return out def _str_section(self, name): @@ -290,7 +282,7 @@ def _str_section(self, name): if self[name]: out += self._str_header(name) content = textwrap.dedent("\n".join(self[name])).split("\n") - out += self._in_container(content, name) + out += content out += [''] return out From a999e3bcc8d8e065e3f4adf499ba5762f11c787b Mon Sep 17 00:00:00 2001 From: Joel Nothman Date: Wed, 15 Nov 2017 19:13:36 +1100 Subject: [PATCH 3/3] Tests and avoid wrapping members --- doc/example.py | 8 ++ numpydoc/docscrape_sphinx.py | 5 +- numpydoc/tests/test_docscrape.py | 150 ++++++++++++++++++------------- 3 files changed, 97 insertions(+), 66 deletions(-) diff --git a/doc/example.py b/doc/example.py index 425c8928..9210037c 100644 --- a/doc/example.py +++ b/doc/example.py @@ -120,3 +120,11 @@ def foo(var1, var2, long_var_name='hi'): """ pass + + +class Foobar: + """Hello + """ + + def do_something(self): + "world" diff --git a/numpydoc/docscrape_sphinx.py b/numpydoc/docscrape_sphinx.py index 84dec5b5..bb4fe4ee 100644 --- a/numpydoc/docscrape_sphinx.py +++ b/numpydoc/docscrape_sphinx.py @@ -58,7 +58,8 @@ def _str_indent(self, doc, indent=4): return out def _wrap_section(self, content, name, directive='rst-class'): - return (['.. %s:: numpydoc-section %s' % (directive, _name_to_class(name)), + return (['.. %s:: numpydoc-section %s' % (directive, + _name_to_class(name)), ''] + self._str_indent(content)) def _str_signature(self): @@ -274,7 +275,7 @@ def _str_member_list(self, name): out += [hdr] out += [''] - out = self._str_header(name) + self._wrap_section(out, name) + out = self._str_header(name) + out return out def _str_section(self, name): diff --git a/numpydoc/tests/test_docscrape.py b/numpydoc/tests/test_docscrape.py index 8fa3d23f..832025a2 100644 --- a/numpydoc/tests/test_docscrape.py +++ b/numpydoc/tests/test_docscrape.py @@ -477,49 +477,59 @@ def test_sphinx_str(): :Parameters: - mean : (N,) ndarray - Mean of the N-dimensional distribution. + .. rst-class:: numpydoc-section numpydoc-parameters - .. math:: + mean : (N,) ndarray + Mean of the N-dimensional distribution. - (1+2+3)/3 + .. math:: - cov : (N, N) ndarray - Covariance matrix of the distribution. + (1+2+3)/3 - 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). + cov : (N, N) ndarray + Covariance matrix of the distribution. + + 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 - The drawn samples, arranged according to `shape`. If the - shape given is (m,n,...), then the shape of `out` is is - (m,n,...,N). + .. rst-class:: numpydoc-section numpydoc-returns + + 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. + In other words, each entry ``out[i,j,...,:]`` is an N-dimensional + value drawn from the distribution. - list of str - This is not a real return value. It exists to test - anonymous return values. + list of str + This is not a real return value. It exists to test + anonymous return values. :Other Parameters: - spam : parrot - A parrot off its mortal coil. + .. rst-class:: numpydoc-section numpydoc-other-parameters + + spam : parrot + A parrot off its mortal coil. :Raises: - RuntimeError - Some error + .. rst-class:: numpydoc-section numpydoc-raises + + RuntimeError + Some error :Warns: - RuntimeWarning - Some warning + .. rst-class:: numpydoc-section numpydoc-warns + + RuntimeWarning + Some warning .. warning:: @@ -586,14 +596,16 @@ def test_sphinx_yields_str(): :Yields: - a : int - The number of apples. + .. rst-class:: numpydoc-section numpydoc-yields + + a : int + The number of apples. - b : int - The number of bananas. + b : int + The number of bananas. - int - The number of unknowns. + int + The number of unknowns. """) @@ -873,23 +885,27 @@ def test_use_blockquotes(): line_by_line_compare(str(doc), ''' :Parameters: - **abc** : def + .. rst-class:: numpydoc-section numpydoc-parameters - ghi + **abc** : def - **jkl** + ghi - mno + **jkl** + + mno :Returns: - **ABC** : DEF + .. rst-class:: numpydoc-section numpydoc-returns + + **ABC** : DEF - GHI + GHI - **JKL** + **JKL** - MNO + MNO ''') @@ -1119,11 +1135,13 @@ def no_period(self): :Parameters: - f : callable ``f(t, y, *f_args)`` - Aaa. + .. rst-class:: numpydoc-section numpydoc-parameters + + f : callable ``f(t, y, *f_args)`` + Aaa. - jac : callable ``jac(t, y, *jac_args)`` - Bbb. + jac : callable ``jac(t, y, *jac_args)`` + Bbb. .. rubric:: Examples @@ -1131,31 +1149,33 @@ def no_period(self): :Attributes: - t : float - Current time. + .. rst-class:: numpydoc-section numpydoc-attributes - y : ndarray - Current variable values. + t : float + Current time. - * hello - * world + y : ndarray + Current variable values. - :obj:`an_attribute ` : float - Test attribute + * hello + * world - no_docstring : str - But a description + :obj:`an_attribute ` : float + Test attribute - no_docstring2 : str + no_docstring : str + But a description - :obj:`multiline_sentence ` - This is a sentence. + no_docstring2 : str - :obj:`midword_period ` - The sentence for numpy.org. + :obj:`multiline_sentence ` + This is a sentence. - :obj:`no_period ` - This does not have a period + :obj:`midword_period ` + The sentence for numpy.org. + + :obj:`no_period ` + This does not have a period .. rubric:: Methods @@ -1179,11 +1199,13 @@ def test_templated_sections(): :Parameters: - f : callable ``f(t, y, *f_args)`` - Aaa. + .. rst-class:: numpydoc-section numpydoc-parameters + + f : callable ``f(t, y, *f_args)`` + Aaa. - jac : callable ``jac(t, y, *jac_args)`` - Bbb. + jac : callable ``jac(t, y, *jac_args)`` + Bbb. """)