Need Attributes displayable like param list

[jnothman]

I've not investigated when/whether there was a change in numpydoc, but scikit-learn has long relied on Attributes (as per docstring, rather than than descriptors on the class) being listed like Parameters. See old docs at http://scikit-learn.org/0.18/modules/generated/sklearn.linear_model.LogisticRegression.html for instance.

We've merged a recent numpydoc into scikit-learn master, which uses _str_member_list to render Attributes, rather than _str_param_list. See new docs at http://scikit-learn.org/dev/modules/generated/sklearn.linear_model.LogisticRegression.html. The listing looks more like methods, and hence like what you get out of autosummary for descriptors, but it altogether (and particularly the type spec) looks wrong. I'm not sure how those type specs work well for any users of Attributes.

To fix scikit-learn's needs, I propose that we extend the Jinja templating of numpy_docstring.rst such that instead of just rendering strings with e.g. {{ attributes }}, we have Jinja statements like:

{% members_list Attributes %}

or perhaps Jinja filters like:

{% raw_attributes | members_list %}

but unless we want to compose filters, I'm not sure the benefit of this.

Would this be acceptable?

[stefanv]

I don't know why this change was introduced, but I agree that it doesn't convey the information we intended in the rendered documentation.

[jnothman]

If you consider it altogether a bug, I'd be very happy with a solution that's not about customisation.

…

On 21 Jul 2017 3:49 am, "Stefan van der Walt" ***@***.***> wrote: I don't know why this change was introduced, but I agree that it doesn't convey the information we intended in the rendered documentation. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#102 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAEz68bVAnbu4anFKWPQd12eSRlqhDPBks5sP5M1gaJpZM4Odaiw> .

[stefanv]

I would; thoughts @pv?

[pv]

The attributes list renders attributes that have docstrings as an autosummary list, including links etc for them. So formatting it as a class member list was on purpose, not accidental.

[jnothman]

that's along the lines of what I'd presumed, @pv. But we don't have links to further docs and type specs are unreadable.

…

On 21 Jul 2017 8:34 am, "Pauli Virtanen" ***@***.***> wrote: The attributes list renders attributes that have docstrings as an autosummary list, including links etc for them. So formatting it as a class member list was on purpose. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#102 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAEz6yoDkVzHC_6oCxxvWNcCsvxw2Vdaks5sP9XfgaJpZM4Odaiw> .

[stefanv]

Don't we use them exactly like we do parameter lists?

[jnothman]

One of the problems is that descriptors like property are attributes with docstrings of their own On 21 Jul 2017 8:42 am, "Stefan van der Walt" <notifications@github.com> wrote: Don't we use them exactly like we do parameter lists? — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#102 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAEz6xm9clWY8UCi1MXbqwFc1GGGnSyYks5sP9fegaJpZM4Odaiw> .

[amueller]

@pv sorry, I didn't understand the explanation.

[pv]

@amueller: for an example, look here https://scipy.github.io/devdocs/generated/scipy.spatial.Delaunay.html --- some of the attributes are properties and have docstrings of their own.

[pv]

@stefanv: no, not necessarily --- in some cases it's just a list of the attributes without any explanations, similar to the Methods section.

I'm not saying that it cannot be changed, but that how these sections have been used can vary.

[stefanv]

The SciPy docs look pretty awful too :/

[pv]

Well, I'm not going to argue against that :)

[jnothman]

So basically there's a hack to make documented attributes and autosummaried attributes look sort of similar, but the autosummary ones would frankly be better displayed like parameters too, were that possible.

…

On 22 July 2017 at 05:10, Pauli Virtanen ***@***.***> wrote: Well, I'm not going to argue against that :) — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#102 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAEz6_kfNejHwGLSTWNEpv95du7o2-IZks5sQPeMgaJpZM4Odaiw> .

[jnothman]

I think the ideal functionality, ensuring backwards compatibility, would:

• list autosummary and docstring-listed members together in the one listing
• adopt the ordering provided in the docstring
• summarise the description provided in the dosctring of the member where it can be resolved (as autosummary does), otherwise the description provided in the parent docstring
• still ensure that sphinx-autogen works for autosummary entries
• display with a definition list in order to (a) look like parameter listings; and (b) support block markup in the description

This is like extending autosummary to support:

• specified descriptions where the member cannot be accessed
• outputting a definition list rather than a table

The latter point could be achieved by patching upstream in sphinx perhaps to have a :layout: definition-list switch in autosummary. The former is harder to achieve because AutoSummary expects the entire content of the directive to be whitespace-separated names to be summarised. So again, this could potentially be achieved upstream with a :provided-descriptions: flag which causes it to parse the content differently. Not sure sphinx would ever accept these kinds of changes, but AutoSummary is pretty rigid as it stands.

Also, extending/reimplementing autosummary will break sphinx-autogen.

The best I can come up with in terms of keeping all of this functionality (without touching sphinx upstream) is:

• copy and modify the AutoSummary directive as NumpyDocAutoSummaryHack to support the definition list output and the provided-descriptions input, while still taking advantage of AutoSummary features such as docstring and signature mangling.
• translate docstrings to something hacky like the following so that they get picked up as an invocation of our hack directive, while also matching autogen's regex for autosummary:

.. numpydoc-autosummary-hack::
    .. autosummary::
        :toctree:

        these
        members
        can
        be
        autosummarised

    these
    members
    can
    be
    autosummarised
    others : array-like
        can not be autosummarised

I assume this is unmaintainable madness, but I'm not sure where to find the right compromise.

From scikit-learn's perspective, changing the member list for attributes back to a parameter listing would suffice most/all of the time.

[amueller]

So how about a switch to on how to parse? I don't like to get involved with autosummary tbh.

[jnothman]

Do you mean a switch on how to display? Yes, this is fine as long as we don't need things autosummarised

…

On 1 Aug 2017 6:19 am, "Andreas Mueller" ***@***.***> wrote: So how about a switch to on how to parse? I don't like to get involved with autosummary tbh. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#102 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAEz6_1elAcy88QhPaIzrDkaeauJGcpUks5sTjbRgaJpZM4Odaiw> .

[amueller]

sorry, yes, how to display, I guess. And we haven't needed autosummaries yet... so global config would be the easiest work-around.