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

[latosha-maltba]

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

[mgeier]

What theme are you using?

All themes derived from basic should be fine, because this is handled:

https://github.com/sphinx-doc/sphinx/blob/f8878bb0b67df6e56ca95c003a41edd9eb59d79e/sphinx/themes/basic/static/basic.css_t#L539-L554

For example: https://insipid-sphinx-theme.readthedocs.io/en/0.2.3/showcase/sections.html#local-table-of-contents

[latosha-maltba]

I encountered this in multiple themes. For a more systematic approach I looked at the themes provided by sphinx-themes.org. Sadly, the .. content:: directive does not render anything (bug pending). However, I found a list with "simple" in the admonitions and compared those to the list generated by .. toctree::

In total there were 113 themes, 41 showed a different style for the lists (probably because of the <p> but I have not verified that). At least some (possibly all) of these themes do not include basic.css. About 23 themes showed different spacing for the second level. I classified those as "possibly flawed" but have not investigated the source of the problem.

So about 40% of themes might be affected.

shows flaw: ----------- asteroid-sphinx-theme astropy-sphinx-theme Caktus catalyst-sphinx-theme f5-sphinx-theme guzzle-sphinx-theme hachibee-sphinx-theme hbp-sphinx-theme insegel kotti_docs_theme Logilab lsst-sphinx-bootstrap-theme murray oe-sphinx-theme ovs-sphinx-theme psyneulink-sphinx-theme quark-sphinx-theme romnnn-sphinx-press-theme solar-theme bernardphp.com theme sphinx-better-theme sphinx-boost sphinx-catalystcloud-theme sphinx-fossasia-theme sphinx-material sphinx-modern-theme sphinx-nervproject-theme press sphinx-rigado-theme sphinx-susiai-theme sphinx-theme-material sphinx_theme_pd sphinxjp.themes.sphinxjp starling-theme tibas.tt topos-theme yummy-sphinx-theme agogo bizstyle scrolls sphinxdoc possibly flawed: ---------------- divio-docs-theme faculty-sphinx-theme An Insipid Sphinx Theme (with initially hidden sidebar) karma_sphinx_theme limix-sphinx-theme LSST Design Documents Theme rtcat-sphinx-theme sphinx-aimms-theme Reusable Ansible Theme sphinx-audeering-theme sphinx-boogergreen-theme Documatt Theme sphinx-glpi-theme sphinx-iowmd-theme sphinx_materialdesign_theme sphinx-mdolab-theme sphinx-pdj-theme sphinx-theme sphinx-ustack-theme sphinx-veldus-theme sphinx-zon-theme stanford-theme ydoc-theme not flawed: ----------- Alabaster classic Furo Read the Docs Theme aiohttp-theme cloud_sptheme dask-sphinx-theme edx-sphinx-theme enthought-sphinx-theme Flask groundwork-sphinx-theme jupyter-sphinx-theme Maisie-Sphinx-Theme Mozilla's sandstone theme pietroalbini-sphinx-themes PyData Sphinx Theme pylons-sphinx-themes (pylons) Python Documentation Theme pytorch-sphinx-theme renga-sphinx-theme renku-sphinx-theme sphinx_adc_theme Sphinx Book Theme sphinx-bootstrap-theme Celery Theme sphinx-compas-theme sphinx-corlab-theme sphinx-enos-theme sphinx_hand_theme sphinx-nameko-mw-theme sphinx-nameko-theme sphinx-opnfv-theme sphinx-pangeo-theme sphinx-readable-theme sphinx-redactor-theme TYPO3 theme for docs.typo3.org Unreal Engine Docs Theme (unofficial) sphinxbootstrap4theme sphinxjp.themes.basicstrap sunpy-sphinx-theme wild_sphinx_theme zerovm-sphinx-theme haiku nature pyramid traditional unknown ------- sphinx_drove_theme (did not render toc) sphinx-ioam-theme (did not render toc) sphinx_sizzle_theme (did not scroll)

[tk0miya]

The docutils; a base library of reStructuredText has started to generate <p> tags for each paragraph on generating HTML5 (At HTML4 era, neadless <p> tags are suppressed). Therefore, the contents directive generates them now. On the other hand, the toctree directive is a custom directive of Sphinx, not a reST standard one. It does not generate <p> tags even after the HTML5 era. I think toctree directive should be fixed as the contents directive does.

[latosha-maltba]

Sounds reasonable although I still wonder whether using <p> inside a toc list is (philosophically) the correct usage of a paragraph element. Nevertheless, I'll consider unifying the HTML-tree of those directives (either at docutils' end or at sphinx's end) more important than having a philosophical dispute. :-)