diff --git a/doc/example.py b/doc/example.py index c55d64df..bc6e5217 100644 --- a/doc/example.py +++ b/doc/example.py @@ -121,3 +121,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 640efa7b..c9a96dc1 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) @@ -53,6 +57,11 @@ def _str_indent(self, doc, indent=4): out += [' '*indent + line] return out + 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 [''] if self['Signature']: @@ -76,19 +85,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): @@ -189,25 +198,25 @@ def _str_param_list(self, name, fake_autosummary=False): """ out = [] if self[name]: - out += self._str_field_list(name) - out += [''] 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 and self.use_blockquotes: out += [''] elif not desc: # empty definition desc = ['..'] - 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 @@ -226,7 +235,6 @@ def _str_member_list(self, name): """ out = [] if self[name]: - out += ['.. rubric:: %s' % name, ''] prefix = getattr(self, '_name', '') if prefix: @@ -268,6 +276,8 @@ def _str_member_list(self, name): out += [fmt % ("**" + param.strip() + "**", desc)] out += [hdr] out += [''] + + 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 fa3f700f..fbb277d7 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,32 +1149,34 @@ 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 @@ -1180,11 +1200,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. """)