Reconsider dark mode default behavior

[philippjfr]

I really love, love, love the work on the dark theme (and pydata-sphinx-theme in general) but having just tried it on some of our websites I'm wondering whether adding the toggle (and the default_mode: 'auto' behavior) should be opt-in by default. What I found was that since my system is set to dark mode it automatically switched the website to dark mode on render.

Now the dark mode probably works fabulously for websites that consist primarily of text and code, but as soon as you have any rich output such as pictures, plots, etc. the dark mode is visually very painful because in most cases these contents cannot easily be adapted to accommodate both modes. Let's take a matplotlib plot with transparent background as example:

Not only is the white on black contrast glaring but the axis labels are basically invisible. Any MathJax equations presumably would have the same issue and become basically invisible (although I have not tested this). Similarly now let's look at some bokeh content:

Now you could say that this is our job to ensure that bokeh correctly toggles themes based on the media query. That's possible true but practically it means that while this is not handled any bokeh output will look terrible when rendered with v0.9.

Since adapting all the contents to render nicely in dark mode will take many library authors some time, I would suggest that at least initially the dark theme switch and the auto default behavior be opt-in. Alternatively, I would suggest documenting how to disable them easily, as this required some digging in the source code:

html_theme_options = {
...
    "navbar_end": ["navbar-icon-links"],
}

html_context.update({
    "default_mode": "light"
})

and causes errors in the pydata_sphinx_theme JS since the switch can't be found.

[drammock]

+1

I've also noticed that there is apparently no memory of a user's dark mode setting? E.g., if I manually change from auto to light mode, that choice doesn't persist through closing/re-opening the browser (though maybe that should be a separate issue)

[12rambau]

@philippjfr first thanks for your nice comments, then I would like to add some prescision to this sitution:

• The dark theme is now using a simpler set of variable making it way easier to update from your side (ENH: simplify color variables #659)
• we are also supporting some common libs like sphinx-panels (Add panels support #641) to aline to other themes like Furo
• Since images can be an issue we added the only-dark and only-ligh class that can help you display the rich content in only one of the theme.
• I'll soon be adding this behaviour for the logos (Support a logo for the dark theme #674)

That being said I realize that's a lot of work on documentation maintainers so yes the auto mode shouldn't be opt-in by default. I have added this "default_mode" parameter back in #540. Sorry if I add forgotten to document it I'll do it ASAP.

@drammock the selected mode is saved in LocalStorage and I add the feeling that was sufficient on my computer I'll check again.

[philippjfr]

Thanks for the quick and detailed reply! I've had some issue with getting the default_mode working consistently for me but I suspect that is user error (or rather I guess it got overridden by the setting that was already persisted to LocalStorage).

On the only-light and only-dark CSS classes that is indeed helpful but the problem we're having is that we generate almost all of our docs from notebooks. So now we'd have to generate two versions of the output (at least for stuff that generates images) and for bokeh plots we will somehow have to figure out if we can apply a theme conditionally based on the media query. So for now I would suggest that there be some way to disable the toggle cleanly as well.

[12rambau]

You could use "light" as default_mode and remove the theme_switcher from the navbar and you should be good to go isn't it ?

html_theme_options = {
   #...,
   "navbar_end": ["navbar-icon-links"]
}

[philippjfr]

Removing the theme switcher like that seems to cause some JS errors which show up in the console.

[12rambau]

didn't think about that. we should silence the js if the theme-switcher is nowhere to be found on the page

[choldgraf]

Hey all - I thanks @philippjfr for sharing your experience. I can see how it'd be frustrating to have all the nicely-generated image outputs suddenly get lost in blackness 😄

So it sounds like the steps to close this are:

• Confirm that default_mode works as expected, and @philippjfr please provide feedback on how docs could be better, IMO user error can almost always be improved with better docs!
• Double check there aren't errors that pop up when the switcher is removed from the navbar.

I added a block-release label to this one since it sounds like there are actually some bugs in the toggler behavior

[jarrodmillman]

@choldgraf @12rambau I missed this and made the 0.9.0 release. Is that OK? Should I yank it from PyPI? I am also happy to make a 0.9.1 or 0.10.0 soon if that would help.

[12rambau]

IMO it's fixed by #692 but I'll let @philippjfr confirm

[philippjfr]

Running a documentation build on our CI now, will report back when it's done.

[choldgraf]

If we need to change something I'd vote for a patch release relatively quickly