.. contents:: entries have an additional paragraph compared with .. toctree:: entries

.. toctree:: and .. contents:: generate different DOM structure with the HTML builder. More precisely, .. contents:: wraps its list elements in paragraphs while .. doctree:: does not. Compare:

For .. toctree::

<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="content.html">Header 1</a></li>
<li class="toctree-l1"><a class="reference internal" href="content.html#header-2">Header 2</a></li>
<li class="toctree-l1"><a class="reference internal" href="content.html#header-3">Header 3</a></li>
<li class="toctree-l1"><a class="reference internal" href="content.html#header-4">Header 4</a></li>
</ul>
</div>

For .. contents::

<div class="contents topic" id="contents">
<p class="topic-title">Contents</p>
<ul class="simple">
<li><p><a class="reference internal" href="#header-1" id="id1">Header 1</a></p></li>
<li><p><a class="reference internal" href="#header-2" id="id2">Header 2</a></p></li>
<li><p><a class="reference internal" href="#header-3" id="id3">Header 3</a></p></li>
<li><p><a class="reference internal" href="#header-4" id="id4">Header 4</a></p></li>
</ul>
</div>

(Note the additional <p>.)

A consequence of this is for example that themes which style paragraphs to have gaps between them (e.g. via margins), have large gaps in the contents TOC. Since .. contents:: is a table of contents and its elements are the headlines, it seems more appropriate to not wrap the header in an paragraph tag. I did not test other builders (which might exhibit similar behaviour) and did not investigate what the internal AST/doctree representation of these two constructs is.

Tested with Sphinx 3.3.1 and current HEAD (633c5ad9c6f4511e3016dd451f17ace1ad160fb2 as of this writing).

Minimal working example:

$ mkdir testdoc
$ cd testdoc
$ touch conf.py
$ cat > index.rst <<<END
.. toctree::

   content
END
$ cat > content.rst <<<END
.. contents::


Header 1
========

Header 2
========

Header 3
========

Header 4
========
END
$ mkdir build
$ sphinx-build -b html . build

Reproduce the issue with the minimal example in index.rst and content.rst, using sphinx-build -b html and the HTML builder. Compare the generated output for .. contents:: and .. toctree::, then trace their doctree or rendering entry points. Done means contents entries no longer contain the additional paragraph element without regressing the existing structure.