Skip to content

Fix: Napoleon NumpyDocstring incorrect section ordering - #14188

Open
DavidAGInnovation wants to merge 10 commits into
sphinx-doc:masterfrom
DavidAGInnovation:fix/napoleon-section-ordering
Open

Fix: Napoleon NumpyDocstring incorrect section ordering#14188
DavidAGInnovation wants to merge 10 commits into
sphinx-doc:masterfrom
DavidAGInnovation:fix/napoleon-section-ordering

Conversation

@DavidAGInnovation

Copy link
Copy Markdown

Closes #13180. Implements section reordering in NumpyDocstring._parse to ensure 'Attributes' and 'Methods' appear after 'Parameters', matching numpydoc standard logic.

@AA-Turner

Copy link
Copy Markdown
Member

The ty failures can be ignored (reported at astral-sh/ty#1970), but please fix the other lint failures.

@DavidAGInnovation
DavidAGInnovation force-pushed the fix/napoleon-section-ordering branch 5 times, most recently from 8fc1fb2 to 1d2b57d Compare December 17, 2025 05:31
@DavidAGInnovation

Copy link
Copy Markdown
Author

Fixed the CI / Python 3.12 (Docutils 0.21) failure: it was Git’s working-tree-encoding conversion choking on working-tree-encoding=iso-8859.

  • Updated sphinx/.gitattributes to use working-tree-encoding=ISO-8859-1

  • Renormalized the fixtures so the repo stores UTF‑8 while the working tree stays Latin‑1:

    • sphinx/tests/roots/test-root/wrongenc.inc
    • sphinx/tests/roots/test-warnings/wrongenc.inc

@AA-Turner AA-Turner left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

please revert all unrelated changes

…x-doc#13180)

Implements section reordering in NumpyDocstring._parse to ensure 'Attributes'
and 'Methods' sections appear after 'Parameters', matching numpydoc standard
logic.

This is achieved by collecting sections during parsing then reordering them
before generating the final parsed lines.
@DavidAGInnovation
DavidAGInnovation force-pushed the fix/napoleon-section-ordering branch from d07e1c8 to f97e19f Compare December 18, 2025 00:16
@DavidAGInnovation

DavidAGInnovation commented Dec 18, 2025

Copy link
Copy Markdown
Author

Done, the tests are running again.

@DavidAGInnovation

Copy link
Copy Markdown
Author

Will this be merged then? @AA-Turner

@AA-Turner

Copy link
Copy Markdown
Member

There's been no review yet which is the major blocker to merging. It'd be helpful to reviewers to have tests and a CHANGES entry in this PR, though.

A

@DavidAGInnovation

Copy link
Copy Markdown
Author

Done @AA-Turner

@DavidAGInnovation

Copy link
Copy Markdown
Author

Do you think it's ready to be merged now? @AA-Turner

Comment thread sphinx/ext/autosummary/generate.py
Comment thread tests/test_builders/test_build_html_numfig.py
@DavidAGInnovation

Copy link
Copy Markdown
Author

Thanks for the feedback. I removed the unrelated autosummary changes, restored the numfig marker, and fixed the ty checkout failure by correcting the Latin-1 fixture encoding configuration. Focused tests, ty, and Ruff pass locally. Ready for another review.

@jdillard

@DavidAGInnovation

Copy link
Copy Markdown
Author

Addressed the review feedback on the original PR:

The original PR's focused tests, ty, and Ruff checks pass locally.

@DavidAGInnovation

Copy link
Copy Markdown
Author

Additional note: the current ty release has started reporting hundreds of baseline diagnostics on master, while the repository's locked Ty version passes. I isolated that reproducibility fix in draft PR #14573: #14573

@jdillard

jdillard commented Aug 3, 2026

Copy link
Copy Markdown
Member

Closing until the PR description is updated in accordance with the AI policy, which is intended to ensure appropriate human oversight. I can reopen once the description is updated.

@DavidAGInnovation

Copy link
Copy Markdown
Author

No AI use here. @jdillard

@jdillard jdillard reopened this Aug 3, 2026
@jdillard

jdillard commented Aug 3, 2026

Copy link
Copy Markdown
Member

Can you remove the unrelated changes (you've had to be asked 3 times now and you keep reintroducing new ones). Those changes are addressed in #14467

@DavidAGInnovation

Copy link
Copy Markdown
Author

Thanks for pointing this out, and apologies for reintroducing them. I’ve removed the unrelated .gitattributes and wrongenc.inc changes from this PR; those remain covered by #14467. This PR now contains only the Napoleon section-ordering implementation, regression test, and changelog entry. @jdillard

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

Successfully merging this pull request may close these issues.

bug: napoleon: numpydoc: incorrect section ordering for classes

3 participants