What is the correct order for Class sections?

[lucascolley]

https://numpydoc.readthedocs.io/en/latest/format.html#class-docstring states that the Attributes section should be "located below the Parameters section". In practice, docscrape works with the order:

• ...
• Parameters
• Returns
• ...
• See Also
• Notes
• References
• Examples
• Attributes
• Methods

This seems deliberate, as https://github.com/numpy/numpydoc/blob/54dbc890fdecc4c2e170e208ed2edc05bb62202a/numpydoc/tests/test_docscrape.py#L1258

tests that Examples comes above Attributes and Methods.

However, this seems to create some weird doc pages, like https://scipy.github.io/devdocs/reference/generated/scipy.interpolate.CubicHermiteSpline.html. Is it really intentional that Attributes and Methods come below References and Notes? When reading the style guide, I interpret it as immediately below the Parameters section, which seems to make intuitive sense.

If this is intentional, then we should update the wording of the style guide to make it more clear. I'm pretty sure this is a mismatch though, so I have opened gh-571 to change the orders in docscrape.

x-ref https://github.com/scipy/scipy/issues/21099

[larsoner]

I think the test is probably wrong and the style guide should be the authority here. Appearing after references and notes seems like it must be wrong.

[lucascolley]

Cool, if there aren't any counterarguments after a few days I'll modify the test such that Attributes and Methods are located below Parameters and above Returns.

[larsoner]

Closed via #571