Skip to content

Class Attributes section in different place than documented #331

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

Closed
QuLogic opened this issue Aug 24, 2021 · 3 comments
Closed

Class Attributes section in different place than documented #331

QuLogic opened this issue Aug 24, 2021 · 3 comments

Comments

@QuLogic
Copy link

QuLogic commented Aug 24, 2021

The class docstring section says to use the same sections as "above", meaning as in functions, and that "An Attributes section, located below the Parameters section, may be used to describe non-method attributes of the class". When this is rendered the Parameters and Attributes sections are separated by Notes, References, and Examples.

Now, the class docstring docs don't say that Attributes must immediately after Parameters, but ordering has always been important (#68), and having HTML docs be in a different order than in-code can make writing them confusing.

@FirefoxMetzger
Copy link

I've noticed this as well in the scipy docs

https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.OptimizeResult.html#scipy.optimize.OptimizeResult

which implicitly depends on Notes being placed after Parameters, because it makes a relative reference in the notes ala "the above attributes". I've submitted a PR downstream (scipy/scipy#14693) for this specific instance, but it feels a bit like treating symptoms 😄

Could we move the Attributes section to immediately follow Parameters like @QuLogic suggested?

@timhoffm
Copy link
Contributor

Seems to be addressed by #571.

@mdhaber
Copy link
Contributor

mdhaber commented Feb 24, 2025

Indeed it does. Thanks, all.

@mdhaber mdhaber closed this as completed Feb 24, 2025
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

4 participants