Skip to content
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.

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

What is the correct order for Class sections? #572

Closed
lucascolley opened this issue Jul 9, 2024 · 3 comments
Closed

What is the correct order for Class sections? #572

lucascolley opened this issue Jul 9, 2024 · 3 comments

Comments

@lucascolley
Copy link
Contributor

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

def test_class_members_doc_sphinx():

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 scipy/scipy#21099

@larsoner
Copy link
Collaborator

larsoner commented Jul 9, 2024

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
Copy link
Contributor Author

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
Copy link
Collaborator

Closed via #571

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants