Code snippets in dark theme are unreadable

[raiyankamal]

Documentation

When python docs are viewed in dark theme, code snippets are put against a light colour background. This makes white letters unreadable. Please see attached screenshot.

This screenshot was taken at: https://docs.python.org/3.8/library/csv.html

Steps to reproduce:

1. Visit https://docs.python.org/3.8/library/csv.html
2. Select theme "Dark" from the drop down menu in the top right corner.
3. Scroll to see any code snippet.

Linked PRs

• [3.9] gh-115349: Pin theme to fix code snippets #115351
• [3.8] gh-115349: Pin theme to fix code snippets (GH-115351) #115404

[terryjreedy]

This only affect the 3.8 and 3.9 docs and for those I confirm the white on white problem with Firefox on Windows. 3.7 and before have no dark theme. For 3.10 and after the dark theme snippet have a dark background that is just slightly lighter than the regular dark background. If possible, the 3.10 dark theme should be backported. Whether this should affect the 3.8 and 3.9 releases is up to the release manager. @ned-deily ?

[ned-deily]

The release manager would be @ambv.

[hugovk]

I susect the problem is that 3.8 has an old pinned Sphinx version 2.4.4, but the theme is unpinned and the newest:

https://github.com/python/cpython/blob/3.8/Doc/requirements.txt

It is trying to apply dark mode but failing. IIRC the theme requires Sphinx 3 or newer.

The minimal fix is probably to pin the theme to an older version that still works with Sphinx 2 (and no dark theme).

Otherwise, we should upgrade Sphinx, and maybe some other dependencies and our own custom extensions. And it would be a good idea to pin the theme too.

---

And to prevent this kind of thing in the future, let's consider pinning the docs deps for branches as they leave the bugfix phase and enter security only.

[hugovk]

The minimal fix is probably to pin the theme to an older version that still works with Sphinx 2 (and no dark theme).

I've transferred this back to the CPython repo to use the issue number for this.

[hugovk]

PRs merged, let's close this.

The 3.8 and 3.9 docs will be deployed during their next releases, which as luck would have it, should be this week.

[terryjreedy]

3.8.19 and 3.9.19 were released March 19, 2024. However, accessing the 3.8 and 3.9 docs displays doc for 3.8.18 and 3.9.18, not the new releases, and the problems remain. #118199 is the new issue.