numpy / numpy/numpydoc

Make numpydoc respect `autodoc_member_order`

Open
#142 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

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

Description

autodoc comes with the parameter autodoc_member_order, which can be set to one of {'alphabetical', 'groubwise', 'bysource'}: http://www.sphinx-doc.org/en/stable/ext/autodoc.html#confval-autodoc_member_order

numpydoc doesn't respect that parameter, but always orders class attributes and methods alphabetically, first here, through inspect
https://github.com/numpy/numpydoc/blob/8c1e85c746d1c95b9433b2ae97057b7f447c83d1/numpydoc/docscrape.py#L613
and then again here
https://github.com/numpy/numpydoc/blob/8c1e85c746d1c95b9433b2ae97057b7f447c83d1/numpydoc/docscrape.py#L591

wouldn't it be relatively simple to make numpydoc respect the parameter by following what autodoc does?

it retrieves the order of definitions in the source file via the Parser attribute .deforder
https://github.com/sphinx-doc/sphinx/blob/a605f2b61907ec768c79890b5073089c1931ac4e/sphinx/pycode/parser.py#L464
and orders attributes using this line where tagorder is the deforder above
https://github.com/sphinx-doc/sphinx/blob/a605f2b61907ec768c79890b5073089c1931ac4e/sphinx/ext/autodoc/__init__.py#L786

cheers,
alex

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.

Research direction

Start in numpydoc/docscrape.py at the two sorting points referenced in the issue, then compare Sphinx's Parser.deforder and autodoc ordering logic. Determine how autodoc_member_order reaches numpydoc and support the stated ordering modes without the current unconditional alphabetical ordering. Done means class attributes and methods follow the configured order.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.