Add option to use member listing for attributes

[jorisvandenbossche]

Related to the discussion in #106 (comment).
There was not really agreement on the way forward, but opening this PR to more easily show what my proposed change would be, and to show that it a minor change.
It does add yet another entry to the option list, that is true, but code wise everything is already there.

[jnothman]

Need to double check that we summarise the docstring in this case such that we won't include any block structure (e.g. tables, lists) which is why we moved back to param lists

[jorisvandenbossche]

Need to double check that we summarise the docstring in this case such that we won't include any block structure (e.g. tables, lists) which is why we moved back to param lists

I don't really follow your comment on what or how to check (I don't know the history of why the move from member list to param list was done. I thought this was for visual reasons).
But note that the exact same code is used to generate the methods listing as well, so if there is no problem in that case, I wouldn't expect problems here.

[jnothman]

Yes, you may be right that it applies there, but I think separate listings of methods are uncommon: you'd expect methods to all be described by autosummary. When you give a description in the class docstring, block elements like tables and lists are not rendered with member_list

[jorisvandenbossche]

Ah, OK, I understand what you mean: the description of the attributes if they are listed in the actual class docstring. But, I think the "member listing" will ignore those descriptions, as it purely uses autosummary table, and autosummary will get the description from the first line of the docstring of the attribute.

I can add a test that it is indeed not used, like:

In [22]:     class Foo:
    ...:         """
    ...:         Class docstring.
    ...:         
    ...:         Attributes
    ...:         ----------
    ...:         an_attribute : type
    ...:             Another description with a list that is not used:
    ...:     
    ...:             * item 1
    ...:     
    ...:         """
    ...:         
    ...:         @property
    ...:         def an_attribute(self):
    ...:             """Test attribute"""
    ...:             return None
    ...:     

In [23]: print(str(SphinxClassDoc(Foo, config=cfg)))

Class docstring.













.. rubric:: Attributes

.. autosummary::
   :toctree:

   an_attribute

[larsoner]

@jorisvandenbossche would this allow you to do less monkey-patching of numpydoc for pandas? It looks like if you add the test you mention above, plus a bit of documentation of the new parameter, this should be mergeable.

[jorisvandenbossche]

Yes, that would certainly help for the pandas side. Will try to add a test and docs in the coming days.

[jnothman]

I don't know whether this is the right solution but I suppose can accept it...

[jnothman]

This also needs documentation among the other config options

[jorisvandenbossche]

I don't know whether this is the right solution

What alternative would you propose?

In any case, from the pandas docs point of view (or at least my view point of it :)), the change that numpydoc was a regression. And it would be nice to at least have some way to keep the old appearance.

[larsoner]

To visually confirm what this does, this sort of page:

When setting numpydoc_attributes_as_param_list = False ends up looking like:

Seems like a reasonable option to me -- we might even switch to it -- and it's tested and documented, so +1 for merge from me.

[jorisvandenbossche]

Yep, that's indeed the goal.

There is some logic in there (already existing, as I only restored how it was before in numpydoc) that gets the summary information either from the attribute's docstring, or either from the listing of the attribute in the class docstring. And in the second case, it seems to add the type information in the summary line (eg the "(dict)" in "info (dict) Measurement info" in the above picture). It could be an enhancement that this type info is also added in the first case (if it is listed in the class docstring of course). But since we don't have such cases in pandas, I didn't look into that.

[larsoner]

It could be an enhancement that this type info is also added in the first case

I'm okay with this being a follow-up PR

[rgommers]

LGTM too and have tested on NumPy and SciPy docs. So in it goes. Thanks @jorisvandenbossche, @jnothman and @larsoner

[jorisvandenbossche]

Thanks!