Documentation: dark theme & images

[denballakh]

Documentation

Starting from version 3.12, the Docs now have a dark theme. However, this feature does not affect the images. As an example, please visit https://docs.python.org/3.12/library/pathlib.html.
The page contains an image of an inheritance tree. In the dark theme, the rectangles remain white, which is not visually appealing:

To address this issue, I propose making these images compatible with the dark theme:

Although I'm not an expert in HTML/CSS, a quick search suggests that adding style="filter:invert(1)" to <img> element can help achieve this.

Linked PRs

• gh-103960: Dark mode: invert image brightness #103983
• [3.11] gh-103960: Dark mode: invert image brightness (GH-103983) #104358

[denballakh]

I think this issue is also relevant to https://github.com/python/python-docs-theme

Also filter: hue-rotate(180deg) invert(1) instead of filter: invert(1) works a bit better.
Without hue rotation:

With hue rotation:

[hugovk]

Thanks for the report.

Images/pages to review:

howto/logging.rst - logging_flow.png

https://docs.python.org/3.12/howto/logging.html#logging-flow
Image has white background and no transparency, but filter:invert(1) would help

using/windows.rst - win_installer.png

https://docs.python.org/3.12/using/windows.html#installation-steps
The installer image above. We might need to leave this one because it's a screenshot and might not want to modify the logo colours:

Or, the actual installer dialog now also supports dark mode (at least on macOS, also Windows?), perhaps we could create new screenshots and show the relevant one?

library/pathlib.rst - pathlib-inheritance.png

https://docs.python.org/3.12/library/pathlib.html
The inheritance tree above. Needs fixing, e.g. filter:invert(1)

library/tkinter.messagebox.rst - tk_msg.png

https://docs.python.org/3.12/library/tkinter.messagebox.html
Image has white background and no transparency:

filter:invert(1) might work, but it's a screenshot so maybe we don't want to show a dark mode version if it doesn't have one in reality (I've not checked).

library/hashlib.rst - hashlib-blake2-tree.png

https://docs.python.org/3.12/library/hashlib.html#creating-hash-objects
White background, no transparency, can be inverted:

[hugovk]

See also python/peps#2409 and python/peps#2949 for how we dealt with some images for dark mode on the PEPs site.

[hugovk]

Please see PR python/python-docs-theme#128 to add the class to the theme.

[hugovk]

And please see PR #103983 to add the class to the three diagrams.

I didn't invert the installer or tkinter.messagebox screenshots shown in #103960 (comment) because they're screenshots of real dialogs and inverting would be misleading and potentially confusing. It's okay to have some lighter screenshots in dark mode.

[barneygale]

Inverting the hashlib image makes the shaded areas almost invisible!

[hugovk]

In contrast (no pun intended) to the above, here's how PR #103983 renders it with inverted brightness, but not inverted contrast:

It's not so visible in the original:

What does the shading actually signify here?