sphinx-doc / sphinx-doc/sphinx
Unexpected header rendered for custom Napoleon section alias
Nobody has claimed this yet.
- 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.autodocsphinx.ext.autosummarysphinx.ext.napoleon
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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