Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

WIP: Try wrapping section content in html classes #147

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

WIP: Try wrapping section content in html classes #147

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
3628535
WIP
jnothman Nov 14, 2017
2c0020d
Fix wrapping in classes
jnothman Nov 15, 2017
a999e3b
Tests and avoid wrapping members
jnothman Nov 15, 2017
0f83c96
Merge branch 'master' into classes
jnothman Nov 15, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions doc/example.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -121,3 +121,11 @@ def foo(var1, var2, long_var_name='hi'):
"""

pass


class Foobar:
"""Hello
"""

def do_something(self):
"world"
36 changes: 23 additions & 13 deletions numpydoc/docscrape_sphinx.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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']:
Expand All @@ -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):
Expand Down Expand Up @@ -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
Expand All @@ -226,7 +235,6 @@ def _str_member_list(self, name):
"""
out = []
if self[name]:
out += ['.. rubric:: %s' % name, '']
prefix = getattr(self, '_name', '')

if prefix:
Expand Down Expand Up @@ -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):
Expand Down
152 changes: 87 additions & 65 deletions numpydoc/tests/test_docscrape.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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::

Expand Down Expand Up @@ -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.
""")


Expand Down Expand Up @@ -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
''')


Expand Down Expand Up @@ -1119,44 +1135,48 @@ 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

For usage examples, see `ode`.

: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 <an_attribute>` : float
Test attribute
* hello
* world

no_docstring : str
But a description
:obj:`an_attribute <an_attribute>` : float
Test attribute

no_docstring2 : str
..
no_docstring : str
But a description

:obj:`multiline_sentence <multiline_sentence>`
This is a sentence.
no_docstring2 : str
..

:obj:`midword_period <midword_period>`
The sentence for numpy.org.
:obj:`multiline_sentence <multiline_sentence>`
This is a sentence.

:obj:`no_period <no_period>`
This does not have a period
:obj:`midword_period <midword_period>`
The sentence for numpy.org.

:obj:`no_period <no_period>`
This does not have a period

.. rubric:: Methods

Expand All @@ -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.

""")

Expand Down