Inconsistent spacing between items in "open" lists (regression)

[medmunds]

(This was previously fixed in #590, and again in #705, but has broken again.)

Problem

Docutils distinguishes between "open" and "compact" lists. Open lists are meant to have some vertical space between the list items. Docutils automatically generates an open list if any item has multiple paragraphs/blocks.

The RTD theme tries to add spacing between open list items, but then removes it from some of the items. This looks inconsistent and can make open lists visually difficult to read.

Reproducible Project

Here's an example:

With a "compact" (simple) list:

* Each item is a single paragraph
* Docutils collapses spacing between items
* HTML builder uses CSS class `simple`

The alternative is an "open" (complex) list:

* At least one item has multiple paragraphs (or other
  blocks like code samples).

* Docutils *doesn't* collapse vertical space in open lists.

  This preserves visual grouping of related content,
  making it easier to read.

* Open lists don't have any special CSS class.

* *Every* item should consistently use open spacing.
  (Even single paragraph items like the one above.)

(Btw, the blank lines in the source aren't significant in deciding open vs closed list. Docutils looks only at whether any of the list items have multiple paragraphs.)

Error Logs/Results

Actual current behavior with sphinx-rtd-theme 2.0.0 in the first image, desired behavior in the second. (They'll show side-by-side on a wide enough window.)

Notice the inconsistent spacing in the first image, which makes the open list look like it's two separate lists, rather than a single list of longer items.

Here's an example in the wild. Notice the second of the three bullets gets visually lost from being smooshed into the third bullet.

Expected Results

All items in a single list should use consistent vertical spacing. See the second (right-hand) image above.

The cause seems to be this set of special cases in _theme_rst, which override the open spacing set up immediately above (and then restore parts of it in some cases). It's not entirely clear to me what those special cases are trying to do, but I'm guessing at least part of it is undoing some high-specificity rules in wyrm.

Ideally, the zero margins would only need to be applied for ol.simple and ul.simple (already defined just after the complex rules). I wonder if it would be possible to get rid of all the special cases by changing the selector for complex lists from ol li, ul li to require direct children ol > li, ul > li?

Environment Info

• Python Version: 3.11.6
• Sphinx Version: 7.2.6
• RTD Theme Version: 2.0.0 (but I think this was broken in 1.3.x or earlier)

[medmunds]

Here's a CSS workaround for use with sphinx-rtd-theme 2.0.0:

/* Improve list item spacing in "open" lists.
   https://github.com/readthedocs/sphinx_rtd_theme/issues/1555

   Undoes this rule in non-.simple lists:
   https://github.com/readthedocs/sphinx_rtd_theme/blob/2.0.0/src/sass/_theme_rst.sass#L174-L175
*/
.rst-content .section ol:not(.simple) > li > p:only-child,
.rst-content .section ol:not(.simple) > li > p:only-child:last-child,
.rst-content .section ul:not(.simple) > li > p:only-child,
.rst-content .section ul:not(.simple) > li > p:only-child:last-child,
.rst-content section ol:not(.simple) > li > p:only-child,
.rst-content section ol:not(.simple) > li > p:only-child:last-child,
.rst-content section ul:not(.simple) > li > p:only-child,
.rst-content section ul:not(.simple) > li > p:only-child:last-child {
  margin-bottom: 12px;
}

Add that to any css file that gets loaded after sphinx-rtd-theme's theme.css. E.g., create docs/_static/my-theme.css with the code above, and then in your docs/conf.py:

def setup(app):
    app.add_css_file("my-theme.css")