Simple toggleable dark mode for docs

[rohit-kumar-j]

trafficstars

Preview:

External: https://github.com/MrDogeBro/sphinx_rtd_dark_mode

[google-cla[bot]]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[yuvaltassa]

This is pretty cool!

Unfortunately we have a breaking commit just ahead of you, let us fix that first...

In the meantime, any thoughts on how font colours can be set specifically for dark mode?

[yuvaltassa]

Our fix was submitted, please re-sync so tests pass, thanks.

[rohit-kumar-j]

Done.

For fonts, I think this is the dark.css file. I think it can only to be edited locally as of now. Perhaps a method to pass in a path of a custom_dark_mode.css file would enable custom fonts.

[yuvaltassa]

I'm testing this and while it works nicely, the default appears to be dark mode, so sphinx_rtd_dark_mode.default_dark_mode = False does not seem to do what it should?

Is that not what you get?

[rohit-kumar-j]

Yes, I had that problem. On the repo he says:

After the first time however, this setting has no effect as the users preference is stored in local storage within their browser. This option accepts a boolean for the value. If this option is true (the default option), users will start in dark mode when first visiting the site. If this option is false, users will start in light mode when they first visit the site.

The temporary solution is to make html first, then toggle it to light in the browser and re-make html once again. This time it stores the setting to default light. If we can clear the local storage upon exit, then it the sphinx_rtd_dark_mode.default_dark_mode = False # or True would work.

[saran-t]

@rohit-kumar-j Maybe try hacking away at https://github.com/deepmind/mujoco/blob/main/doc/css/theme_overrides.css to override text colours? That's the mechanism that we used to customise the colour scheme of the standard theme in the first place. (The way I did it was to use Chrome's Inspect to find out which CSS class needs to be overridden.)

Our preferred dark colour at DeepMind is Blue 900 (#14234B), so I'd first try using that as the menu's background colour, Gray 1000 (#3D4045) as the main background colour, Blue 300 (#0B65F3) as the header text colour (basically replacing the current blue text), and see if we can get enough contrast with that combination. We'll also need to replace the red colour used in code blocks, I reckon Red 400 (#F9526B) would do the trick.

[rohit-kumar-j]

Apologies for the late response, JS, CSS, and HTML were new to me and I was figuring out how to implement the dark mode without the extension since the sphinx docs for multiple html_css_files options were rather not userfriendly.

@yuvaltassa, the locked theme problem can now be solved by changing the href in the layout.html instead of the conf.py

<!-- Dark Mode-->
<link id="pagestyle" rel="stylesheet" type="text/css" href="_static/theme_overrides_dark.css">

<!-- Light Mode-->
<link id="pagestyle" rel="stylesheet" type="text/css" href="_static/theme_overrides.css">

I instead made a theme_overrides_dark.css in addition to the theme_overrides.css and modified layout.html to respect the theme overrides. Although I did not edit any of the colors as I am not very good at the .wy-nav properties in the .css files.

The html_css_files option is removed from the conf.py and the theme switching is handled by the JS added on each page by sphinx in the layout.html. It even remembers the theme when we switch websites and across reloads.

Here is a preview of messing around with the switching:

https://user-images.githubusercontent.com/37873142/179370990-dac422c4-f86b-449a-9ec6-6d632518ff66.mp4

[yuvaltassa]

Hi @rohit-kumar-j !

Would you mind taking a look at @kevinzakka's #421 ?

The big win in #421's proposed use of furo is the right-hand sub-TOC which is incredibly useful. You have to try it to see what I mean.

Unfortunately it currently has a few glaring issues. Perhaps we can do some sort of best-of-both-worlds merge of the two proposals? You seem to be pretty good at this, it would be awesome if you took a stab.

Here are the issues in #421 as I see them:

1. General:
   1. The link symbol should not be '#' but the one we have now
   2. I'd prefer only light-dark mode toggle like in your PR, no "auto" mode. The asking-the-browser thing should only happen when you first load the page. This is more of a niggle than a deal breaker.
   3. The bold text seems "less bold", to the point where it's barely different from regular. Compare the current rendering of attribute headers in XML Reference (in red) with the rendering in 421.
2. Light mode:
   1. The table shadows are generally cute but don't work for the table-within-a-table in the schema at the top of XML Reference. If I had to choose I'd just go without shadows.
3. Dark mode
   1. The dark blue and red are too dark (of course making the dark blue lighter means making the regular blue lighter too so they wont be identical).
   2. The table borders become invisible, again look at the top of XML Reference.

I think that just fixing the colours (which you seem to be quite proficient at) and table issues would make a new-and-improved furo-based theme a slam dunk for documentation readability.

[yuvaltassa]

Fixed by 571b703f1ccce0e768554adac82a1da95065bcad