DOC: Document helper for dark mode

[larsoner]

After #540, the first thing I needed to do was to make the main MNE-Python logo responsive. This adds a hint to people for how to do it. (It took me hours because I'm bad at JS!)

FYI I tried the <picture><srcset ...> approach where you look at if it prefers dark to light, but this was not responsive to theme changes.

[larsoner]

@12rambau you might have other better ideas here, too!

[choldgraf]

This is a nice idea! I made a few edits and cleaned up this section in general in the latest commit, what do you think?

[12rambau]

@larsoner thanks for the editing of the doc, I was not super confident with what was written there and I think it' much better.

With regards to the images, It's a tricky subject. On my documentation I decided to continue using directives so that the other builds (epub and pdf) continue to work but I was forced to inject custom js to make the switch between light and dark versions of the images.

Do you think it should be written as well ? (the fact that using pure HTML will prevent pdf build of your images)

[larsoner]

On my documentation I decided to continue using directives... Do you think it should be written as well ? (the fact that using pure HTML will prevent pdf build of your images)

I did the same in the end actually. The <img tag was actually just a simplification to make a point. In practice I actually don't use pure HTML... I use a standard sphinx image directive, give it a mainlogo class, and use document.getElementsByClassName('mainlogo')[0] to access it:

https://github.com/mne-tools/mne-python/blame/main/doc/index.rst#L20-L29

This seemed unnecessarily complicated as I figured people would use the docs as a minimal example of how to tweak the HTML (and the getElementsByClassName seemed less minimal), but I could change the example to use this instead if you think it would help people realize they don't have to abandon a standard directive here!

[larsoner]

Switching to keep standard directive use here's the updated text:

https://pydata-sphinx-theme--626.org.readthedocs.build/en/626/user_guide/customizing.html#define-custom-javascript-to-react-to-theme-changes

[choldgraf]

I like those new changes! This LGTM. I'll hold off on merging for a little bit in case @12rambau would like changes!

[damianavila]

LGTM as well!

[damianavila]

@12rambau, any thoughts before merging it?

[12rambau]

nothing to add from my side

[choldgraf]

Many thanks @larsoner !!