Skip to content

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

Merged
merged 6 commits into from
Oct 2, 2022

Conversation

CAM-Gerlach
Copy link
Member

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

image

image

Fixes #2749 (finally)

@CAM-Gerlach CAM-Gerlach added the infra Core infrastructure for building and rendering PEPs label Sep 28, 2022
@CAM-Gerlach CAM-Gerlach requested review from hugovk, gvanrossum and a team September 28, 2022 04:57
@CAM-Gerlach CAM-Gerlach self-assigned this Sep 28, 2022
@CAM-Gerlach CAM-Gerlach changed the title Style: Further lighten table zebra stripes Style: Fix zebra stripes and further improve table & code presentation Sep 28, 2022
@CAM-Gerlach
Copy link
Member Author

CLA bot isn't triggering for some reason, trying to close and re-open...

@CAM-Gerlach CAM-Gerlach reopened this Sep 28, 2022
@gvanrossum
Copy link
Member

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.

@CAM-Gerlach
Copy link
Member Author

in the light theme it seems you actually darkened the bg color for inline code

Yes, slightly, from #f8f8f8 to #eeeee, which is a consistent shade with the CPython docs at #ecf0f3 for code literals and the rest of the PEP theme palette.

Have you tried just leaving that bg color out (so it's presumably the same as for regular text)?

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

What made you darken it?

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.

As a compromise I would be happy if the color scheme used was the same as in the latest (dev) Python docs

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.

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.

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.

Copy link
Member

@hugovk hugovk left a 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 👍

Copy link
Member

@gvanrossum gvanrossum left a 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!

Copy link
Member

@pradyunsg pradyunsg left a 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.

@CAM-Gerlach CAM-Gerlach changed the title Style: Fix zebra stripes and further improve table & code presentation Style: Fix zebra stripes and improve table & code presentation Oct 2, 2022
@CAM-Gerlach CAM-Gerlach merged commit 326e562 into python:main Oct 2, 2022
@CAM-Gerlach CAM-Gerlach deleted the further-fix-zebra-stripes branch October 2, 2022 00:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
infra Core infrastructure for building and rendering PEPs
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Reduce the contrast in the banding of tables
4 participants