numpy / numpydoc

Numpy's Sphinx extensions
https://numpydoc.readthedocs.io/
Other
302 stars 161 forks source link

What is the correct order for Class sections? #572

Closed lucascolley closed 3 months ago

lucascolley commented 3 months ago

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:

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 commented 3 months ago

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 commented 3 months ago

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 commented 3 months ago

Closed via #571