sphinx-doc / sphinx-doc/sphinx

sphinx.ext.napoleon: napoleon_use_param=True merges "Other Parameters" with "Parameters"

Open
#10,330 0 comments 3 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

extensions:napoleon type:bug
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

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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.