sphinx-doc / sphinx-doc/sphinx
"Keyword Arguments" section created by numpydoc looks poor with default theme when there's a single kwarg.
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
The default theme should probably arrange for the "Keyword Arguments" section header created by numpydoc to fit in a single line, as splitting it in two lines can result in awkward layouts.
How to Reproduce
In a clean directory
$ cat >project.py <<EOF
def foo(*, kwarg):
"""
Foos it.
Keyword Arguments
-----------------
kwarg : int
It's the kwarg.
"""
EOF
sphinx-apidoc . -o . -F -A me -V 0.0 --extensions sphinx.ext.napoleon
PYTHONPATH=. make html
Expected behavior
The "Keyword Arguments" header should not be longer (in lines) than the actual contents of the section.
Your project
N/A, see script above to generate it.
Screenshots

OS
linux
Python version
3.10
Sphinx version
4.3.2
Sphinx extensions
sphinx.ext.napoleon
Extra tools
N/A
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 by reproducing the layout in a clean directory with the provided project.py, sphinx-apidoc command, and make html using the default theme. Inspect the generated HTML and theme styling to identify why a single keyword argument causes the header to wrap. Done means the "Keyword Arguments" header fits in no more lines than the section contents without breaking other generated documentation layouts.
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