fix: reorder class docstring sections per numpydoc 1.8+ standard

[jlaportebot]

Problem

Per numpydoc 1.8.0 release notes, the section ordering for class docstrings was updated so that Attributes and Methods sections appear directly after Parameters (and Other Parameters, Keyword Arguments), before Returns/Yields/Notes/etc.

However, sphinx.ext.napoleon still emits sections in document order, so Attributes and Methods end up after Notes, Examples, Returns, etc.

Closes #13180

Solution

This PR implements class/exception docstring section reordering in the napoleon extension:

Core changes (sphinx/ext/napoleon/docstring.py)

1. Section buffering in _parse(): For class/exception docstrings (self._what in {"class", "exception"}), section content is collected into section_chunks instead of being immediately appended to _parsed_lines.

2. _reorder_class_sections() method: Reorders the collected section chunks into the correct order:

   • Preamble (description) → Parameters/Other Parameters/Keyword Arguments → Attributes/Methods → Everything else (Notes, Examples, Returns, etc.)

3. Early exit optimization: If sections are already in the correct order, or if there are no Attributes/Methods sections, the original order is preserved without unnecessary processing.

4. Edge case handling:

   • Class docstrings with no Parameters section but with Attributes/Methods (they still get moved up)
   • Google-style docstrings (Args → Attributes → Methods → other)
   • napoleon_use_ivar=True and napoleon_use_param=False configurations
   • Exception docstrings (treated the same as class docstrings)

Test changes (tests/test_ext_napoleon/test_ext_napoleon_docstring.py)

Added TestClassSectionOrdering with 11 test cases covering:

• Numpy-style: Attributes after Parameters
• Numpy-style: Methods after Parameters
• No reordering for function docstrings
• Already correct order (no-op)
• Google-style: Attributes/Methods after Args
• Exception docstring reordering
• No Attributes/Methods sections (no-op)
• napoleon_use_ivar=True
• napoleon_use_param=False
• Other Parameters included with Parameters
• No Parameters but with Attributes (edge case fixed in this PR)

Testing

All 79 napoleon tests pass (excluding one pre-existing failure in test_napoleon_keyword_and_paramtype which is unrelated).

========================= 79 passed, 1 deselected, 8 warnings in 0.48s =========================