sphinx-doc / sphinx-doc/sphinx
sphinx.ext.napoleon: napoleon_use_param=True merges "Other Parameters" with "Parameters"
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 parsing by napoleon, when there are parameters are defined in a "Parameters" section and in a "Other Parameters" section, the default setting of napoleon_use_param=True generates reStructuredText where the two groups of parameters will be rendered as a single group of parameters. This results from #8713 which went into 4.0. Previously, the parsing of "Other Parameters" would never use :param:, so would always be rendered as a distinct section.
If this is simply the way that napoleon_use_param=True has to function, I suggest adding a note/warning in the documentation. I was tearing my hair out why the "Other Parameters" section stopped being rendered as a distinct section after I recently updated my Sphinx.
How to Reproduce
>>> import sphinx.ext.napoleon
>>> print(str(sphinx.ext.napoleon.NumpyDocstring("""
... Test
...
... Parameters
... ----------
... x : int
...
... Other Parameters
... -----------------
... y : int
... """)))
Test
:param x:
:type x: int
:param y:
:type y: int
>>> print(str(sphinx.ext.napoleon.NumpyDocstring("""
... Test
...
... Parameters
... ----------
... x : int
...
... Other Parameters
... -----------------
... y : int
... """, config=sphinx.ext.napoleon.Config(napoleon_use_param=False))))
Test
:Parameters: **x** (*int*)
:Other Parameters: **y** (*int*)
Expected behavior
The preservation of the "Other Parameters" as a distinct section with default settings
Your project
(see code snippet)
Screenshots
No response
OS
Windows
Python version
3.8.8
Sphinx version
4.5.0
Sphinx extensions
sphinx.ext.napoleon
Extra tools
No response
Additional context
No response
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
Start with sphinx.ext.napoleon.NumpyDocstring and the Config option napoleon_use_param, then run the two reproduction snippets from the issue. Trace how the Parameters and Other Parameters sections are rendered with the default configuration. Done means the expected distinction is preserved by the behavior or clearly documented, with coverage for both configuration values.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100