Skip to content

Format attributes like parameters #106

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

Merged
merged 5 commits into from
Sep 9, 2017
Merged

Format attributes like parameters #106

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
5f641a1
Format attributes like parameters
jnothman Aug 6, 2017
f09abc8
Test autosummary-like behaviour
jnothman Aug 21, 2017
a1e7eba
Some cleaning and docs
jnothman Sep 7, 2017
7fa273c
More docs
jnothman Sep 7, 2017
c917226
Note on methods
jnothman Sep 7, 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
64 changes: 59 additions & 5 deletions numpydoc/docscrape_sphinx.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,21 +79,74 @@ def _str_returns(self, name='Returns'):
out += ['']
return out

def _str_param_list(self, name):
def _str_param_list(self, name, fake_autosummary=False):
out = []
if self[name]:
if fake_autosummary:
prefix = getattr(self, '_name', '')
if prefix:
autosum_prefix = '~%s.' % prefix
link_prefix = '%s.' % prefix
else:
autosum_prefix = ''
link_prefix = ''
autosum = []

out += self._str_field_list(name)
out += ['']
for param, param_type, desc in self[name]:
param = param.strip()

display_param = '**%s**' % param

if fake_autosummary:
param_obj = getattr(self._obj, param, None)
if not (callable(param_obj)
or isinstance(param_obj, property)
or inspect.isgetsetdescriptor(param_obj)):
param_obj = None
obj_doc = pydoc.getdoc(param_obj)

if param_obj and (obj_doc or not desc):
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@pv, this is the logic for constructing the description when the attribute corresponds to an object. Firstly, above, we only link to the attribute's autodoc if it has either a docstring or is not described in the numpydoc (and I'd be okay with removing the or not desc, except that it is current behaviour).

If it has a docstring, we try to emulate autosummary: split the object's docstring at its first blank line. Then take a prefix up to the first . if present, or the whole first paragraph otherwise.

I should probably test this logic more thoroughly before merge.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it turns out the "or not desc" logic here wasn't working because desc is being provided as [''] when there is no description line. Which means no one depends on this logic, which means I'm getting rid of it because it's weird (unless you can think of a use-case for linking to an autogen page where the attribute has no docstring).

# Referenced object has a docstring
autosum += [" %s%s" % (autosum_prefix, param)]
# TODO: add signature to display as in autosummary
# Difficult because autosummary's processing
# involves sphinx's plugin mechanism, for
# directives only
display_param = ':obj:`%s <%s%s>`' % (param,
link_prefix,
param)
if obj_doc:
# Overwrite desc. Take summary logic of autosummary
desc = re.split('\n\s*\n', obj_doc.strip(), 1)[0]
# XXX: Should this have DOTALL?
# It does not in autosummary
m = re.search(r"^([A-Z].*?\.)(?:\s|$)", desc)
if m:
desc = m.group(1).strip()
else:
desc = desc.partition('\n')[0]
desc = desc.split('\n')

if param_type:
out += self._str_indent(['**%s** : %s' % (param.strip(),
param_type)])
out += self._str_indent(['%s : %s' % (display_param,
param_type)])
else:
out += self._str_indent(['**%s**' % param.strip()])
out += self._str_indent([display_param])
if desc:
out += ['']
out += self._str_indent(desc, 8)
out += ['']

if fake_autosummary and autosum:
if self.class_members_toctree:
autosum.insert(0, ' :toctree:')
autosum.insert(0, '.. autosummary::')
out += ['..', ' HACK to make autogen generate docs:']
out += self._str_indent(autosum, 4)
out += ['']

return out

@property
Expand Down Expand Up @@ -250,7 +303,8 @@ def __str__(self, indent=0, func_role="obj"):
'notes': self._str_section('Notes'),
'references': self._str_references(),
'examples': self._str_examples(),
'attributes': self._str_member_list('Attributes'),
'attributes': self._str_param_list('Attributes',
fake_autosummary=True),
'methods': self._str_member_list('Methods'),
}
ns = dict((k, '\n'.join(v)) for k, v in ns.items())
Expand Down
22 changes: 14 additions & 8 deletions numpydoc/tests/test_docscrape.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,8 @@
from nose.tools import (assert_equal, assert_raises, assert_list_equal,
assert_true)

assert_list_equal.__self__.maxDiff = None

if sys.version_info[0] >= 3:
sixu = lambda s: s
else:
Expand Down Expand Up @@ -975,17 +977,21 @@ def x(self):

For usage examples, see `ode`.

.. rubric:: Attributes
:Attributes:

.. autosummary::
:toctree:
**t** : float
Current time.
**y** : ndarray
Current variable values.
:obj:`x <x>` : float
Test attribute

x
..
HACK to make autogen generate docs:
.. autosummary::
:toctree:

===== ==========
**t** (float) Current time.
**y** (ndarray) Current variable values.
===== ==========
x

.. rubric:: Methods

Expand Down