-
-
Notifications
You must be signed in to change notification settings - Fork 1.6k
Style: Fix zebra stripes and improve table & code presentation #2805
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
Style: Fix zebra stripes and improve table & code presentation #2805
Conversation
CLA bot isn't triggering for some reason, trying to close and re-open... |
I wouldn't dare actually review CSS, but I looked at the screenshots, and in the light theme it seems you actually darkened the bg color for inline code. Have you tried just leaving that bg color out (so it's presumably the same as for regular text)? What made you darken it? As a compromise I would be happy if the color scheme used was the same as in the latest (dev) Python docs -- except I can't seem to find much uniformity in that: when a code word is a link it has no darker bg, when it isn't, I've found examples where code has a darker bg and examples where it doesn't, sometimes on the same page, so that's still a mystery. |
Yes, slightly, from
Yes, but its much harder to tell apart from regular text (and looks as much like medium-bold text as anything), more difficult to tell exactly where the literal begins and ends, and not consistent with the CPython docs and the great majority of Sphinx themes (the built-in ones, Lutra, Furo, etc).
This was initially to, as we discussed on Discord, ensure it was at least darker than the zebra striping (with an additional offset applied depending on whether it was on a colored stripe, to maintain relative contrast). However, I retained it in the final version, as it ensured the background color is actually properly visible to most people on most monitors (as it was nearly invisible before, at least in light mode, while it was very visible in dark mode, which I made less so), is consistent with the CPython docs, and helps convey the semantic difference between code literals and object references.
It is now essentially the same shade as the CPython docs theme, slightly simplified to follow the standardized and a11y contrast-tweaked PEP theme color palette.
This is because they are using different markup that have different semantic meaning (just like the other things you're used to seeing :). References to defined names/objects, like functions, classes, methods and modules, have no background (e.g. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks good, thanks!
And horizontal ruled lines are also a good second option to zebra stripes, according to the a11y study results mentioned on #2734 👍
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is because they are using different markup that have different semantic meaning (just like the other things you're used to seeing :). References to defined names/objects, like functions, classes, methods and modules, have no background (e.g.
:func:`print`
,:mod:`sys`
,:class:`sqlite3.Connection
, etc), while regular literals (Path("some/path/to"file")
,r"\b(\w)+\b"
,OSError: The file could not be found
, etc) do. However, these constructs have not always been used consistently in Python's documentation, so it isn't always obvious at first glance unless looking at the source.
Having gotten used to Markdown, these distinctions are fuzzy to me (and apparently to many doc authors, given their inconsistent usage). But this doesn't bother me quite in the same way as zebra stripes, because at least it draws attention to a semantic difference. :-)
Godspeed!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
One minor comment on the CSS, which can definitely be addressed in a follow-up.
Followup to #2740 and #2734
After further discussion with @gvanrossum and a lot of experimentation, tweaking and testing, I've resolved the remaining outstanding issues with styling for tables, and (I believe) substantially improved their presentation overall, along with related fixes. Initially, this PR further lightened the zebra stripes in tables and fixed the relative contrast issues with the code literal backgrounds and the table stripes. However, after adding the horizontal/vertical rules and darker header to maintain sufficient contrast and readability, in the end all the shades of grey ended up being unnecessarily distracting and overcomplicated, so I removed the zebra stripes altogether, with the end product being very similar to a slightly contrast-refined version of the tables in the CPython docs (that others mentioned they favored).
In addition, I also addressed a couple small related issues, namely ensuring readable and consistent contrast for inline code backgrounds and text for the dark and the light themes, plus adding a bit of needed padding for such, and separating the default admonition color from the background accent and improving its own contrast, and a bit of related refactoring.
Before/after screenshots
Fixes #2749 (finally)