hugovk, 1 month ago

🆕🎨📚 New change to the Python docs theme:

To make them more visible, we've added coloured sidebars and text to the "New in version x.y" / "Changed in version x.y" / " Deprecated since version x.y" directives.

Before: https://docs.python.org/3.11/library/importlib.html#importlib.abc.InspectLoader.source_to_code

After: https://docs.python.org/3/library/importlib.html#importlib.abc.InspectLoader.source_to_code
#Python #docs #documentation #colour

The same but now there's a green vertical bar on the left of "New in version 3.4" which itself is green. "Changed in version 3.5" is yellow with a yellow sidebar. "Deprecated since version 3.4" is red with a red sidebar.

jdlbt, 1 month ago

@hugovk This is great, thank you!

Any chance these changes can be retroactively applied to older Python versions docs? When developing libraries, we often have to look specifically for these notes in the docs of multiple Python versions, e.g 3.9 - 3.12.

hugovk, 1 month ago

@jdlbt
You're welcome!

They've been applied to 3.12 and 3.13.

Only security fixes are allowed for 3.8-3.11, but if there's a fix that means the docs are rebuilt for 3.10-3.11, they'll pick up the new theme.

But not for 3.8 and 3.9, they're pinned to an old version of the theme for other reasons.

https://devguide.python.org/versions/

ethantyping, 1 month ago

@hugovk ooo this looks great! As a followup you may want to check the colors work for people who are color blind if you haven't already.

hugovk, 1 month ago

@ethantyping Thanks! Yes, this follows the WCAG guidelines that say:

"Color is not used as the only visual means of conveying information, indicating an action, prompting a response, or distinguishing a visual element."

https://www.w3.org/WAI/WCAG21/Understanding/use-of-color.html

As before the change, the information is conveyed via text, and not colour alone.

I also checked the contrast ratio meets at least the WCAG AA guidelines (4.5), with all but one meeting AAA (7.0).

https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum

https://github.com/python/python-docs-theme/pull/185

hugovk, 1 month ago

@ethantyping We're also hoping to do an accessibility audit, which may start with an evaluation of the colours used throughout the theme.

daoud, 1 month ago

@hugovk great stuff. Thanks for bringing the underlining of links to my attention. I think we're going to need to make some changes to Mwmbl...

hugovk, 1 month ago

@daoud https://adrianroselli.com/2016/06/on-link-underlines.html is a good overview:

"Remember, this is for addressing how links are styled in the body of a page, the narrative content, where they sit among blocks of unlinked text. Not navigation, not footers, not page controls, etc."

We initially underlined navigational links, but it was a bit much, so removed those. Technical docs have lots of text in code format; we moved the underline down a bit for those so as not to obscure underlines.

__sharky__, 1 month ago

@hugovk looks good 👍

pbx, 1 month ago

@hugovk Nice work. I'd say the increased line spacing on the new version (that's what I'm seeing on my Android phone anyway) is also a nice readability improvement.

hugovk, 1 month ago

@pbx Thanks! Yes, that's good too :)

PS I like the "Rivers I've lived near" in your bio. Mine: Dee (name means "goddess"), Ouse ("water"), Avon ("river"), Mersey ("boundary river"), Vantaa ("place behind a riverbed")