sphinx-doc / sphinx-doc/sphinx

invalid html (nested paragraphs) generated for function parameters

Open
#9,141 1 comment 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

domains:py type:bug
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

Describe the bug
The generated html contains

<li><p><strong>x</strong> – <p>hello</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>bye</p>
</div>
</p></li>

Notice the outer paragraph that comes with li, which contains inner paragraphs, that's invalid in html. I noticed this while looking at #4227 (apparently the outer p was not there in 2017). I don't know if the issue comes from sphinx or docutils (I have 0.16).

To Reproduce
a.py:

def f(y,x):
    '''
    :param y: hello
    :param x: hello

        .. note::
            bye'''
    pass

empty __init__.py, sphinx-quickstart, add .. autofunction:: a.f to index.rst and 'sphinx.ext.autodoc' to extensions in conf.py, run PYTHONPATH=. make clean html, and look at _build/html/index.html.

Expected behavior
Valid (x)html. The outer <p> doesn't look very useful to me (and the inner div and p seem redundant), but I am not an expert in html.

Environment info

  • OS: Linux Debian testing x86_64
  • Python version: 3.9.2
  • Sphinx version: 3.4.3 (from debian) or 4.1.0 (from github)
  • Sphinx extensions: sphinx.ext.autodoc

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

Reproduce the issue with a.py, empty init.py, index.rst, and conf.py using PYTHONPATH=. make clean html, then inspect _build/html/index.html. Compare the generated parameter markup with the expected valid HTML and determine whether the behavior comes from Sphinx or docutils. Done means the nested paragraphs are no longer emitted for this example.

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.