basic theme: CSS margin overhaul

[mgeier]

Fixes #7544.

Some details might still be missing, but I think this is at least a step in the right direction.

As mentioned in #7544 (comment):

I think the "right" solution would be to remove the margin-bottom from the :last-child and add a consistent padding: 7px on all sides.
The problem is that this would be quite a big change in multiple themes, and people might consider it a "breaking change".

It turned out that I had only to change the basic theme, but it's still quite a big change, and some might consider it "breaking".

Any suggestions for improvements?

[tk0miya]

I'm not an expert in HTML/CSS. So I don't have a comment on this. So let's see what effect to 3rd party themes after merging.

[return42]

You should create a PR with your suggested improvements.

Are you joking? Can you image how much work I have to repair all my projects using up to date sphinx-doc (3.1) .. Did you ever compiled the sphinx-doc project itself? Did you ever had a look on long contents directives? Do you ever compiled one of the big searx projects (like python docs) ..

Or did you just fumble with theses small docutils examples?

You should test elementary patches and not release code and test it by the users, awaiting that they send you patches repairing all you fumbled broken.

If you are not knowing what to do just git-revert the patches.

[mgeier]

You should create a PR with your suggested improvements.

Are you joking?

Not at all!
Please make a PR (or multiple)!

Can you image how much work I have to repair all my projects using up to date sphinx-doc (3.1) ..

For the short term, it should be sufficient to pin sphinx<3.1 in your dependencies. So yes, very little work.

Then we can try to fix the issues together, which will need some work done by someone.

Once they are fixed, you can un-pin your dependencies and everything will be honky-dory.

Did you ever compiled the sphinx-doc project itself?

Yes, I did.

Ironically, the Sphinx docs don't use that many Sphinx features.

Did you ever had a look on long contents directives?

Yes, I did.

Do you ever compiled one of the big searx projects (like python docs) ..

No, I've never heard about it.

Or did you just fumble with theses small docutils examples?

Of course not.

I just used the docutils example in #7838 (comment) to illustrate the visual inconsistencies.

A longer list wouldn't add any useful information.

You should test elementary patches and not release code and test it by the users, awaiting that they send you patches repairing all you fumbled broken.

Sure, I tested it quite thoroughly, but I can never guarantee that nothing will break.

Also, it is quite hard to get the attention of potential reviewers for every single PR for Sphinx. But it is really easy to get user's attention after things are released (as your comments have shown).

If you are not knowing what to do just git-revert the patches.

I would say that I know to some degree what I'm doing, but I'm certainly not an expert. I'm very much open to suggestions for improvements!

I think the changes #7657 are a net improvement, so I wouldn't completely revert it.
But there are for sure some things that can still be improved by further PRs.

---

While I'm at it, please let me also respond to your comment #7838 (comment), in order not to disturb the constructive discussions over there:

@mgeier please stop changing basic CSS !!!

I don't have concrete plans to change further CSS in the basic theme, but I can't guarantee that I won't find further problems that I would like to fix.
But for now, I've already done all the changes I wanted to be done:

• basic theme: Add right margin to footnote/citation labels #7481
• basic theme: CSS spacing for code blocks with captions and line numbers #7482
• basic theme: Avoid clashes between sidebar and other blocks #7484
• basic theme: set "clear: both" on "highlight*" divs #7540
• basic theme: Make admonition/topic/sidebar scrollable #7542
• basic theme: Add top and bottom margins to tables #7543
• Align equation numbers at the right margin #7572
• basic theme: CSS margin overhaul #7657 (this one)
• basic CSS: avoid unnecessary padding to the left of line numbers #7717

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

As mentioned above, ad-hoc work-arounds are probably not the best use of your time.

how do you get the idea to change the basic CSS so massively without having to test it broadly.

Good question!

I just saw that there are problems with the basic CSS and tried to fix them.
I was fully aware that people might complain, but I was also aware that whatever they complain about will also be fixable. And in the end, we all will have a better Sphinx.

---

... and #7838 (comment):

@mgeier wrotes ..

I would like to argue that the new spacing is more consistent,

Not with the toc directive which is rendered much more compact.

If everything is compact, it's still consistent.
I'm not arguing that compact or non-compact is better, as long as it is consistent.

And I think the discussions in #7838 look very promising. I think it is realistic that we will get compact lists (for you) that are still consistent (for me).

[mgeier]

@return42 Please check out #7852, which should fix the list spacing issues.