sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.45k stars 2.1k forks source link

Unexpected header rendered for custom Napoleon section alias #12877

Open fabcor-maxiv opened 2 weeks ago

fabcor-maxiv commented 2 weeks ago

Describe the bug

For a custom Napoleon section alias we would expect the original header label to be rendered, but it is the alias label that is rendered instead.

How to Reproduce

conf.py:

project = "Thing"

extensions = (
    "sphinx.ext.autodoc",
    "sphinx.ext.autosummary",
    "sphinx.ext.napoleon",
)

autodoc_default_options = {
    "members": True,
}

autosummary_generate = True

HW_PROPS = "Hardware Properties"
napoleon_custom_sections = (
    (HW_PROPS, "params_style"),
    ("HwProps", HW_PROPS),
)

index.rst


API
===

.. autosummary::
    :toctree: autosummary
    :recursive:

    thing

thing.py

class Thing:
    """The thing

    HwProps:
        color (str): The color of the thing.
    """

We would expect the section header in the generated HTML documentation to be the original label Hardware Properties, but instead it is the alias label HwProps.

Environment Information

Platform:              linux; (Linux-6.1.0-25-amd64-x86_64-with-glibc2.36)
Python version:        3.12.2 (main, Mar 11 2024, 16:50:09) [GCC 12.2.0])
Python implementation: CPython
Sphinx version:        8.0.2
Docutils version:      0.21.2
Jinja2 version:        3.1.4
Pygments version:      2.18.0

Sphinx extensions

No response

Additional context

No response