Repository navigation
[ENH]: Sphinx plot directive to support dark mode #25983
Description
Problem
We are looking to deploy pydata-sphinx-theme on our docs (astropy/astropy#14867). The theme has a nifty light/dark mode toggle. Very quickly it is apparent that the generate plot using matplotlib's .. plot:: directive stays in light mode no matter what. The result could be pretty jarring.
Proposed solution
Would be nice for the .. plot:: directive to follow light/dark mode. Though you might want it as opt-in just in case some users do not want that, especially if you decide to use the CSS color-inversion trick that scipy does in https://github.com/scipy/scipy/blob/c1b803b66a3e9f0416f3feafc6d4cf24d2ec98e2/doc/source/_static/scipy.css#L133 .
Thank to @ksunden for pointing that out to me!
Activity
ksunden commentedon May 25, 2023
mechanistically, I expect this may be similar to #25515, just instead of dpi, would be theme... not quite sure how to hook into the browser, but conceptually it is similar, at least.
I suspect that there are plenty of plots in our own docs that would not want it (e.g. when explicitly selecting colors that would not work on a dark background), but honestly many of them (if they are just using default color cycle/text colors), it may be better.
I would expect to have a global toggle as well as an individual plot directive toggle.
pllim commentedon Dec 23, 2023
Update: I finally got around to try using https://github.com/scipy/scipy/blob/c1b803b66a3e9f0416f3feafc6d4cf24d2ec98e2/doc/source/_static/scipy.css#L133 in astropy but it didn't work.
So I had to revert that change from astropy/astropy#15783
asmeurer commentedon May 12, 2024
Does matplotlib have a native ability to make a dark mode version of a plot or would that setup have to be part of every plot directive codeblock?
The way Furo handles this is it has
only-lightandonly-darkcss classes for images, which show/hide the image for the correct mode https://pradyunsg.me/furo/reference/images/#different-images-for-dark-light-mode. Do other themes work the same way? It would be nice if there could be a universal theme independent solution to this that just worked automatically.I think this is solvable now by setting a custom template + custom pre_code that generates two plots and puts the appropriate classes on them. But that's not a good long term solution because the template is pretty complex and if you use a custom one, it would not stay updated with any upstream updates to the extension.
asmeurer commentedon May 12, 2024
Another option would be for matplotlib to generate SVGs that do the right thing in dark mode. Is that something that it already supports? See sympy/sympy#25702 for examples of how that can work.