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
List items have extra vertical space since Sphinx 3.1.x #7838
Comments
@eric-wieser I guess this cames from your changes in 3.1. Could you check this please? |
@tk0miya: I don't remember editing any stylesheets. |
Yes, this came from me, and yes, this is a change in behavior, but I'm not sure whether it's a "breakage" or an "un-breakage". This is also the behavior you see when you open the HTML page without any CSS. This is the same as Github Markdown uses for "loose" lists: "Tight" list without
"Loose" list with
I think the real question is: can we get Sphinx to generate list items without |
I would like to explain my motivation (or rather one of the motivations) for the change in #7657: Using the Bullet Lists
------------
- A bullet list
+ Nested bullet list.
+ Nested item 2.
- Item 2.
Paragraph 2 of item 2.
* Nested bullet list.
* Nested item 2.
- Third level.
- Item 2.
* Nested item 3. Before Sphinx version 3.1, this looked like this (using the Starting with Sphinx 3.1, it looks like this: I would like to argue that the new spacing is more consistent, but there is for sure room for improvements! |
Thanks @mgeier for the response and detailed explanation! The style may be "more correct" for So it seems to me, if you want to change this, the way forward would be to first emit list items without As for the more consistent layout: Your example from the docutils demo document uses a nested list. I'm not sure I follow you even for the nested case (I find the first rendering easier to the eye, because nested items are grouped together). But for the case of flat lists, list items are effectively interleaved with blank lines, which means they look less cohesive on a page, and are not separated well from other page elements. Also, this wastes a good amount of screen real estate. I think the links at the top of the issue description demonstrate this well. Disclaimer: I'm not a Sphinx expert, and certainly not an expert in web design. I don't mind at all to fix this in my own CSS instead (but I do think it's in need of fixing). |
Oh, sorry eric-wieser. it's my bad. Indeed, this was changed by mgeier.
No proper way (in reST). The reST parser always generates a paragraph node for each list item. Of course, you can do it with your own extension. But users can't control it via mark up. |
Sorry to say, but PR #7657 breaks nearly all layouts .. IMO these patches should be rewind complete. @mgeier please stop changing basic CSS !!! i'm pretty annoyed because i have been trying to find out how to fix this broken layout in customizing for hours ... and i can do that in all my projects .. thanks for all the work .. how do you get the idea to change the basic CSS so massively without having to test it broadly. |
Is the solution here to add a docutils |
I remember trying to figure out the deal with lists at some point, and it may be worth looking into the docutils writers first. If I'm not mistaken the paragraph-less lists are called "compact lists" there, and a quick grep (for "compact" in the writers folder) indicates that there may be a difference between the HTML 4 and HTML 5 writer. Maybe they are simply not implemented for HTML 5? If so it may be best to fix docutils (or at least patch the HTML 5 writer in Sphinx). |
I'm wrong, the HTML4 writer actually overloads a method in the base class. So if anything the HTML5 writer has better compact list support. |
Ah, here's the relevant snippet from the HTML4 writer
It looks like this feature is quite deliberately not provided in the HTML5 writer, as it seems to have been dismissed as "a CSS problem". I don't agree with this choice of docutils, semantically a list of paragraphs is distinct from a list of sentences. |
I understand their reasoning (it's kind of a hax), and indeed there is a difference in semantics. .. list-style:: compact
* item1
* item2
.. list-style:: paragraph
* subitem1
* subitem2 I'm not sure how that could be implemented, but in the end there will probably be cases where one would like to override the default behaviour. |
@mgeier wrotes ..
Not with the toc directive which is rendered much more compact. |
FWIW: here is my hot-fix (haven't tested on all my projects): li > p:first-child {
margin-top: 0;
}
li > p:last-child {
margin-bottom: 0;
}
div.admonition dl {
margin-bottom: 0;
} |
It's a docutils node that's there from the beginning: In [57]: import docutils.nodes
...: import docutils.parsers.rst
...: import docutils.utils
...: import docutils.frontend
...:
...: def parse_rst(text: str) -> docutils.nodes.document:
...: parser = docutils.parsers.rst.Parser()
...: components = (docutils.parsers.rst.Parser,)
...: settings = docutils.frontend.OptionParser(components=components).get_default_value
...: s()
...: document = docutils.utils.new_document('<rst-doc>', settings=settings)
...: parser.parse(text, document)
...: return document
...:
In [58]: d = parse_rst("""
...: testing
...:
...: * This is a short list
...: * With one line
...:
...: And
...:
...: * This is a much longer list
...:
...: With multiple lines
...:
...: * And another item""")
In [62]: print(d.pformat())
<document source="<rst-doc>">
<paragraph>
testing
<bullet_list bullet="*">
<list_item>
<paragraph>
This is a short list
<list_item>
<paragraph>
With one line
<paragraph>
And
<bullet_list bullet="*">
<list_item>
<paragraph>
This is a much longer list
<paragraph>
With multiple lines
<list_item>
<paragraph>
And another item hence my suggestion that maybe we handle this with a transform pass. |
I remember that I tried to fixed it years ago, but when I saw the Surceforge process I stopped thinking about. I guess it is time to create a git-fork of docutils / Goodger will never use git and the development goes down to zero and when they made patches in the past they break projects using sphinx-doc. Me and myriade of other developer like to contribute are asking Goodger for a change from svn to git, but Goodger is completly ignorand (did you ever read all the "migrate to git" threads .. the discussion is really annoying). BTW: there is a git mirror https://repo.or.cz/w/docutils.git of the SVN repo. |
I'm not sure changing docutils necessarily is the best approach. The parser can not know when a list should be compact or not. Post-transforms may change the tree, e.g., expand a seemingly small item into a multi-paragraph text. So having a late post-transform, or some logic in the HTML writer seems most appropriate to me at the moment, leaning towards the transform. |
Eh, maybe I missed something, but it looks like docutils puts the CSS class
|
Since the CSS classes As I mentioned there, I think some of the CSS classes are assigned to the wrong lists. [UPDATE: I was wrong!] Maybe it would be better to keep ignoring the |
I don't know if that uses the latest https://docutils.sourceforge.io/docs/user/rst/demo.html#contents However, the https://docutils.sourceforge.io/docs/user/rst/demo.html#table-of-contents |
I found a pure CSS solution: #7852 (comment). I mentioned above (#7838 (comment)):
It looks like I was wrong in my assumptions about what exactly "compact" lists are. With my new changes to #7852 the TOC created with the AFAICT, everything works now! |
Thanks for your work @mgeier! I can confirm that my project is rendered correctly with your changes. 🚀 |
FWIW, you can use Some time ago I filed readthedocs/sphinx_rtd_theme#354 to support these in Sphinx RTD theme, and support for that was added. |
This reverts commit 0616684. Since PR sphinx-doc/sphinx#7878 has been merged into Spinx-doc (v3.1.2), this patch is no longer needed: See sphinx-doc project, PR 7838 & 7484 with elementary patch to the basic CSS: - sphinx-doc/sphinx#7838 (comment) - sphinx-doc/sphinx#7484 (comment) Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
Describe the bug
List items in HTML output are displayed with extra vertical space, as if separated by blank lines. Compare the rendering of the feature list in this project, or the screenshots further below:
Tested on a recent Chrome for Mac, see below for environment info.
It appears this is due to changes in
basic.css
between Sphinx 3.0.4 and 3.1.0. See the diff ofbasic.css
at the bottom of this issue description. The stylesheet rules reset the bottom margin of<p>
when nested in<li>
. Apparently this logic was broken in Sphinx 3.1.x for at least one browser.To Reproduce
Steps to reproduce the behavior:
Expected behavior
List items are displayed in a compact way, without vertical spacing amounting to blank line.
Your project
https://github.com/cjolowicz/cookiecutter-hypermodern-python
Screenshots
With Sphinx 3.0.3:
With Sphinx 3.1.0:
Environment info
Additional context
Here is the diff of basic.css from Sphinx 3.0.4 to 3.1.0 which causes the breakage for me. IOW if I revert these changes, the list is displayed correctly.
The text was updated successfully, but these errors were encountered: