-
Notifications
You must be signed in to change notification settings - Fork 1.7k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Inconsistent spacing between items in "open" lists (regression) #1555
Labels
Comments
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") |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
(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:
(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
andul.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 fromol li, ul li
to require direct childrenol > li, ul > li
?Environment Info
The text was updated successfully, but these errors were encountered: