Skip to content
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

First draft of dark theme #44

Open
wants to merge 34 commits into
base: master
from
Open

First draft of dark theme #44

wants to merge 34 commits into from

Conversation

@septatrix
Copy link

@septatrix septatrix commented Feb 5, 2020

This is still unfinished.

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
  • 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

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 (#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

0 0 0 0_8000_html_datetime html

@the-knights-who-say-ni
Copy link

@the-knights-who-say-ni the-knights-who-say-ni commented Feb 5, 2020

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
Copy link

@vitaly-zdanevich vitaly-zdanevich commented Feb 6, 2020

Thank you for your important work!

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

@vitaly-zdanevich
Copy link

@vitaly-zdanevich vitaly-zdanevich commented Feb 6, 2020

Dark scrollbar?

@vitaly-zdanevich
Copy link

@vitaly-zdanevich vitaly-zdanevich commented Feb 6, 2020

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
Copy link
Member

@JulienPalard JulienPalard commented Feb 6, 2020

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
Copy link

@opensource-assist opensource-assist commented Feb 7, 2020

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

@septatrix
Copy link
Author

@septatrix septatrix commented Feb 8, 2020

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
Copy link
Author

@septatrix septatrix commented Feb 11, 2020

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
Copy link
Author

@septatrix septatrix commented Feb 13, 2020

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
Copy link

@zacps zacps commented Feb 14, 2020

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

@septatrix septatrix mentioned this pull request Mar 8, 2020
0 of 2 tasks complete
@septatrix
Copy link
Author

@septatrix septatrix commented Mar 8, 2020

Updated the demo page

@septatrix septatrix changed the title [WIP] First draft of dark theme First draft of dark theme Mar 15, 2020
@vitaly-zdanevich
Copy link

@vitaly-zdanevich vitaly-zdanevich commented Mar 20, 2020

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

@septatrix
Copy link
Author

@septatrix septatrix commented Mar 20, 2020

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
Copy link
Author

@septatrix septatrix commented Apr 4, 2020

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
Copy link

@vitaly-zdanevich vitaly-zdanevich commented Apr 4, 2020

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

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

@septatrix
Copy link
Author

@septatrix septatrix commented Apr 5, 2020

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
Copy link

@vitaly-zdanevich vitaly-zdanevich commented Apr 5, 2020

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?

image

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

@septatrix
Copy link
Author

@septatrix septatrix commented Apr 21, 2020

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
Copy link

@vitaly-zdanevich vitaly-zdanevich commented Apr 22, 2020

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

@septatrix
Copy link
Author

@septatrix septatrix commented May 12, 2020

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.

@septatrix
Copy link
Author

@septatrix septatrix commented Jun 14, 2020

Any update on whether this will get merged @vitaly-zdanevich

@aeros
Copy link
Member

@aeros aeros commented Jun 14, 2020

@theacodes would you care to take a look over this when you find the time? I think a dark theme for docs.python.org would be great and this looks decent at a surface level, but I don't have much proficiency w/ CSS.

@aeros aeros requested a review from theacodes Jun 14, 2020
@vitaly-zdanevich
Copy link

@vitaly-zdanevich vitaly-zdanevich commented Jun 14, 2020

If not making the background a liiiitle bit darker, I have nothing to say, anyway, this is a huge step to the dark ecosystem :)

@septatrix
Copy link
Author

@septatrix septatrix commented Sep 20, 2020

@theacodes any feedback or estimate when you will be able to take a look at this?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

7 participants
You can’t perform that action at this time.