Reconsider position of Attributes and Methods sections

Open
#608 4 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
35/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Stale
Tech stack
python
Domain
documentation

Research direction

Start with the section-order logic in numpydoc/docscrape.py at the linked lines. Review how the current order serves classes versus functions and resolve the open design discussion before changing it. Done means an agreed ordering that keeps class parameters grouped appropriately without disrupting the existing function and method layouts.

Written by the indexing model from the issue text.

Description

#571 changed the section order to move Attributes and Methods right behind Parameters.

The order is now https://github.com/numpy/numpydoc/blob/532cd7d71ceee4e00fd13fa5faf038f2b4d95905/numpydoc/docscrape.py#L118-L137

For classes, we can get the order Paramters > Attributes > Methods > Other Parameters , which IMHO is not quite usable as the Other Parameters are very far away from Parameters.

We have to consider that the ordering should work both for classes and methods. As far as I understand, the motivation for Other Parameters is to deemphasise them and for methods to have the (typically short) sections Returns/Yields/Receives closer to the top.

I propose to move Attributes and Methods below Other Parameters, i.e.

Parameters
Returns
Yields
Receives
Other Parameters
Attributes
Methods
  • There's no change for functions / methods as the don't use Attributes and Methods
  • There's no change for classes without "Other Parameters" because they don't use Returns/Yields/Receives
  • For classes with "Other Parameters" the sequence is "Parameters > Other Parameters > Attributes > Methods", which I think is better because the first two are input values to the construtor, while the other two are properties of the class.

One could argue that one should alternatively not use "Other Parameters" if one wants to render them next to each other anyway. But I claim it's still helpful to de-emphasize additional parameters through that extra section.

Dominant language
Python
Stars
355
Forks
181
Avg merge
1d 9h
Merged PRs (30d)
3

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from numpy/numpydoc

All issues in numpy/numpydoc

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.