Dark theme

[septatrix]

Closes #43.
Closes #101.

Update: I now consider this ready

I have made a crude dark them as requested in #43, however there are still many unfinished areas.
So far I've always tested based on the datetime.rst file from the official docs as an example, though this does not use all styles which need to be changed.

TODO

General areas

• Implement basic dark theme functionality
• Implement proper dark mode syntax highlighting (merged for Sphinx 3.0)
• Check complete docs for missing styles (e.g. find where .refcount and .stableabi are used)
• Add functionality to toggle theme (persistence would require JS or server side code)
  • Maybe add small disclaimer on first visit to show how to change to dark theme (decided not to as it is just another annoying banner like cookies on other websites)
• Add dark mode compatible variants of images (e.g. pathlib images - maybe open issue in cpython repo) or alternatively add a white background for now (out of scope and has to be done in the python repo)

Components / Classes

• Check contrast ratios
  • Fix styles for highlights after a search (kinda, feedback welcome; too bright makes text unreadable, too dark makes highlights hard to spot; went for a halfway point but maybe an outline is better)
• Scrollbars (Dark theme #44 (comment))
• Sidebar collapse panel

Notes

Design decisions

I choose the current main background color based on the header on python.org and went for a different one (#121212 from material design guidelines) for the background color around the edges as I thought this added a bit more depth to it. On second thought however it may be better to go with the single color approach as it is in the official docs. If we then were to the use the darker one this would also improve contrast and leave more space for fine tuning e.g. the anchor/link color.
Most other colors are just from experimenting with the color wheel and by what felt right. The background for syntax however still needs to change but for that topic also see below.

Syntax highlighting

As neither Sphinx nor Pygments support switching themes based on a media query right now this would need to be a bit hacky. I might create an issue there and ask if they would be fine with pull request implementing such functionality (in whatever way though I already have an idea). Otherwise we would need to include another stylesheet after pygments.css overwriting the normal one.

Theme toggling

As not everybody likes to always have a dark theme it may be a good idea to implement theme switching functionality. This could be achieved using either CSS and some label/input magic or plain ole JS (or server side). CSS would be very accessible but not persistent. Therefore I think we should use the CSS way but save the state in a cookie (like we already do for whether the sidebar is expanded or not).

Try it out

Live version

Updated somewhat regularly:
https://septatrix.github.io/cpython-dark-docs/

Screenshot (outdated)

Full size screenshot - rather large

[the-knights-who-say-ni]

Hello, and thanks for your contribution!

I'm a bot set up to make sure that the project can legally accept this contribution by verifying everyone involved has signed the PSF contributor agreement (CLA).

Recognized GitHub username

We couldn't find a bugs.python.org (b.p.o) account corresponding to the following GitHub usernames:

@septatrix

This might be simply due to a missing "GitHub Name" entry in one's b.p.o account settings. This is necessary for legal reasons before we can look at this contribution. Please follow the steps outlined in the CPython devguide to rectify this issue.

You can check yourself to see if the CLA has been received.

Thanks again for the contribution, we look forward to reviewing it!

[vitaly-zdanevich]

Thank you for your important work!

I would like to make background a little bit darker, with less contrast of text.

[vitaly-zdanevich]

Dark scrollbar?

[vitaly-zdanevich]

Just idea - maybe like in Reddit for Android - it is good idea to have Dark theme and AMOLED dark, with #000 as a background?

[JulienPalard]

Thanks for the work on this, I'm bad at UI/UX so I won't say anything more, I just appreciate someone is handling this.

[opensource-assist]

It's already very awesome. I like this colour.

[septatrix]

Thanks for the feedback so far. I will try to incorporate it as far as I can next week but before I finalize it I would like to await the response for dark theme support in Sphinx first.

[septatrix]

Dark scrollbar?

Styling of scrollbars is not easy across browser vendors though I think we may use ::-webkit-scrollbar for Chrome + Safari (+ new Edge) and scrollbar-color (still a working draft) for Firefox.

I currently have a few exams coming up so I probably won't get to implementing it until this weekend

[septatrix]

I did some further improvements and updated the TODO list above...
Here is what I've got so far, feel free to check it out:
https://septatrix.github.io/cpython-dark-docs/ (Docs from cpython repo)

[zacps]

Seems to be missing styles for 'sidebars'. See asyncio.

[septatrix]

I am currently working on finalizing the upstream changes. Additionally I have implemented a persistent disabling of the dark theme however no activation of the dark theme when prefers-color-scheme is light as this would be a bit trickier and ugly.
I will try to update the demo page today.

[septatrix]

Updated the demo page

[vitaly-zdanevich]

I just want to say big THANK YOU again for continuing adding dark theme, this is important for many users.

[septatrix]

Thanks :D It is almost finished now. All that is left to do is think about how to handle images and maybe add an option to the theme to completely disable dark mode in the config. The upstream changes in Sphinx have been merged for 3.x so we should be good merging this next month when Sphinx 3 is released...

[septatrix]

As the Sphinx 3 release is right around the corner I did some fine tuning (e.g. reducing bright contrast to reduce eye strain) and switched to localStorage instead of document.cookies. Finally I implemented implemented a forceDark mode so the dark theme is also available to users without (prefers-color-scheme: dark) so there are now forceLight, forceDark, and auto (default)

If someone would be so kind to make a last review I would be very happy - I updated the live demo and otherwise would say it is ready to be merged :D

[vitaly-zdanevich]

Again - thank you for your work, this is important.

Checked demo right now: I want darker background than this:

[septatrix]

Do you have a color in mind? I was using material design, some code editor themes and a few websites as reference. Most of them were close to the one I choose or at least did not use very dark backgrounds. However using the current mechanism it would be very easy to implement an additional full black AMOLED theme if that is what you want...

[vitaly-zdanevich]

Yes, I want darker background, and I believe many other guys like me :)

In some apps they have not only light or dark themes, but also AMOLED dark, for example Reddit on Android, but I am not sure if we need three states. Maybe #111?

Also I think that vertical line at the left is too bright.

[septatrix]

I dimmed the color a bit and added an indicator what the current theme is in the button.
Regarding the colors I now went for #222 for the bg though I personally am not willing to go any darker. If you check e.g. editor themes most of them are in the range of #222 to #333 as anything below that is very tiring for the eyes after a longer time

[vitaly-zdanevich]

ok, anyway, thank you again for such important work.

[septatrix]

Is there anything you want to be resolved before merging? Otherwise I would be pleased if you would merge this. In case you still want to adjust some colors I am certain you can do so on your own.

[hugovk]

I think this is looking really good!

I agree minor things can be dealt with later, and if we don't find any really major things it would be good to merge and iterate from there.

And I agree Pygments "Monokai" code contrast issues don't really deserve a fix here, they should usually be reported/fixed upstream at https://github.com/pygments/pygments (I've already done a few things for the "Native" dark style used by https://github.com/python/peps).

[hugovk]

On my phone (Android, Samsung S10, Chrome), the search box expands off the screen, which the current docs don't do:

Screenshots

This is partly an existing problem in that -- for some pages -- the whole page can be scrolled to the right (new theme and existing theme), but now the search box now extend to the off-screen section:

Screenshots

[nmstoker]

I'm late to hearing about this but it's good to see this being worked on.

Is the plan to get this out and then refine the design / colour options? (EDIT: sorry, I missed two comments directly above confirming about tuning the colours can come later. In light of that, my points below are more for the next stage 🙂)

I'm viewing it on Firefox Nightly on Android (I'll try to compare with other browsers/computers later on in case there are significant differences).

Right now the colour choices, especially around the various shades of grey, seem quite jarring. I'm no colour expert but I suspect it might look more consistent if most of the background shades came from essentially the same "colour" / hue of grey and largely varied the lightness (subtly). Also having shades of grey and then a pure black header looks odd too.

[pdcastro]

My 2 cents is that I have been using the dark theme preview for a while instead of the of official docs, and I find that the dark theme is a massive improvement just as it is right now. This PR was created 3 years ago and the worse outcome would be for the recent momentum to be lost and the PR to be abandoned. So I would say:

• Fix/change only what is absolutely necessary, i.e. issues that prevent the site from being used. I am not aware of any such issue.
• Get it merged and released.
• Leave other minor issues for future PRs, e.g.:
  • The search box expanding off the screen on mobile.
  • WCAG compliance on color contrast.
  • Comments on color shades and alpha channels.

As soon as this PR is merged and released, invite everyone who commented here on the remaining unaddressed issues to create new corresponding GitHub issues, to be fixed in future PRs by whoever is willing to contribute further.

This is not to dismiss the remaining issues as unimportant. On the contrary, getting this PR merged increases the chance of the remaining issues being addressed because they become doable as smaller pieces of work, by a wider pool of contributors.

Congrats to everyone who put effort creating this PR, contributing and reviewing, especially @septatrix - great job! 👏 🎉

[septatrix]

On my phone (Android, Samsung S10, Chrome), the search box expands off the screen, which the current docs don't do

Fixed

[hugovk]

Current preview link: https://python-docs-theme-previews--44.org.readthedocs.build/en/44/

---

I asked people on Mastodon to try it out and only got positive feedback.

I agree this is good to merge now, and other things can be adjusted in followups.

Thank you!

[pradyunsg]

With #109, I think we can click merge on this?

[hugovk]

Almost! Let's deal with #108 (comment) first.

[joshhacksthings]

@hugovk now that the #108 (comment) has been fixed with #113 , can this now be merged? 😀

[hugovk]

Yes, let's do it.

@septatrix Thank you for all your work on this PR! And to everyone else for the feedback.

[JulienPalard]

Just ran:

docsbuild@docs:/srv/docsbuild$ ./venv-3.12/bin/python -m pip install git+https://github.com/python/python-docs-theme/

manually so maybe in a few hours docs.python.org/dev/ will use the dark theme, I think it's a good way to test it.

[hugovk]

It's now live: https://docs.python.org/dev/

[hugovk]

See also python/cpython#103960. Not a theme issue, we need to adjust some images in CPython docs for dark mode.

Edit: or shall we add CSS to the theme here, like in python/peps#2409 + python/peps#2949?

img.invert-in-dark-mode {
    filter: invert(1) hue-rotate(.5turn);
}

Then we can use it in the docs like:

.. figure:: hashlib-blake2-tree.png
   :alt: Explanation of tree mode parameters.
   :class: invert-in-dark-mode

[hugovk]

Please see PR #128 to add the class to the theme.

[j-ntw]

It's live on python 3.13 docs, but not on previous doc versions as recent as python 3.11. Any chance to push the changes there too?

[hugovk]

This is now live at the main https://docs.python.org site (and 3.12 and 3.13), thanks again @septatrix for all your work and patience!