sphinx-doc / sphinx-doc/sphinx
invalid html (nested paragraphs) generated for function parameters
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 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
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
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