sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.42k stars 2.09k forks source link

invalid html (nested paragraphs) generated for function parameters #9141

Open mglisse opened 3 years ago

mglisse commented 3 years ago

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

tk0miya commented 3 years ago

We need to rewrite the whole of field-list processing. It does not support valid HTML5. #4227 is related to this problem.