sphinx-doc / sphinx-doc/sphinx

Unexpected header rendered for custom Napoleon section alias

Open
#12,877 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

extensions:napoleon python type:bug
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

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
  • sphinx.ext.autodoc
  • sphinx.ext.autosummary
  • sphinx.ext.napoleon

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

Reproduce the issue with conf.py, index.rst, and thing.py using the listed Sphinx extensions, then inspect the generated HTML for the Napoleon section heading. Trace how napoleon_custom_sections maps the HwProps alias to Hardware Properties, and consider the expected original-label behavior done when the generated heading shows Hardware Properties while the documented parameter content remains intact.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.