sphinx-doc / sphinx-doc/sphinx

"Keyword Arguments" section created by numpydoc looks poor with default theme when there's a single kwarg.

Open
#10,032 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

html theme type:bug
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

Screenshot_20211231_002604

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

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 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.