fix docs layout with new dark/light pydata modes

[DirkEilander]

Since v0.9 the pydata sphinx theme has dark/light modes. This ruins our deltares theme css settings. I suggest to simplify our deltares look and stay closer to the pydata style to likely avoid these type of issues in the future.

[DirkEilander]

@JoerivanEngelen has been so kind to fix the deltares-theme css in #132 However the dark/light mode switch is not visible and not dark mode not "dark", see also https://imod.xyz/ I've spent and hour trying to make the deltares blue nav work in both light and dark mode without succes.

That's why I propose an alternative version closer to the default pydata style in #136, see: https://deltares.github.io/hydromt/preview/ Note that the HydroMT logo needs to be simplified for the docs. I've contacted Roel about this.

@IMarth @sibrenloos @hboisgon @Huite @JoerivanEngelen Happy to hear you thoughts on both versions! It would be nice to keep similar layout of the docs between imod-python and HydroMT.

[IMarth]

I really like the style in #136! And it's much better with the night mode. The only thing I was thinking is whether we want to have a larger (blue) Deltares logo in this case? Now we only have this small button that I think not a lot of people would identify it with Deltares.

[Huite]

With how the readability of the dark mode on https://deltares.gitlab.io/imod/imod-python/ looks, it's probably for the best that the button is hidden...

Just sticking to the pydata theme is the easiest, and maybe something I should have done to begin with. Having said that, it does look rather less recognizable. Also requires some tweaking of the logo:

The bezel used by the undersized Deltares logo seems like a fine solution:

I guess it mostly comes down to how important you think a dark mode is. I like dark modes in theory, but they work poorly in combination with figures. As these are quite common, I've set my github theme back to light mode for example.

Looks good in light mode:

But it's quite common to run into trouble with figures, as they have black glyphs on a transparent background:

You can avoid this by using light gray letters, but that's less readable in white mode.

There are also parts which are readable, but kind of ugly (from here):

From a typography point of view, the images cannot really be seen as separated from the surrounding text. For good conversion, we require non-transparent backgrounds (so black glyphs do not disappear). Ideally, in white mode, the figure background is then also white. In dark mode, the contrast between the dark background color and the bright white of the figure background is jarring.

So I guess my thinking is: dark mode is really quite unsatisfying, not sure if it's worth "sacrificing" the blue bar. Keep in mind many other themes do not have a dark mode at all. Then again, the blue bar is kind of nice and recognizable, but hardly essential.

[gijsber]

Personally I like the blue bar of imod.xyz style as it has a nice fit to the Deltares house style, but that said I am not a dark mode user.

[JoerivanEngelen]

Even though I dark mode most applications on my computer (e.g. Total Commander, VSCode, even Windows Office [latter is a bad idea btw]), I'm not a fan of the PyData darkmode yet, because of the reasons layed out by @Huite. It doesn't seem to work so well with other plugins at the moment, though the pydata-theme people are working on improving that e.g. https://github.com/pydata/pydata-sphinx-theme/issues/745.

I like the blue bar template, it does wonders for the "branding" of our software. It makes it clear the software is mainly developed by Deltares, which helps create enthusiasm for our products amongst the MT and heads of the "product line".

The "hidden" dark mode button in the light mode template didn't bother me so much. I view it as a silly easter egg, with the downside that it might confuse users who might mis-click something, though luckily the "mode" button is visible in dark mode, so people can click it again.

[DirkEilander]

Thanks for the feedback @JoerivanEngelen @gijsber @Huite.

I agree that dark mode needs a lot of work with all the images and is not that important and I might actually turn it off based on the examples shown by Huite. However, with the pydata style v0.9 the custom css below also has been broken. These were used to set the color of the nav bar items separate from the right index items and change the color of the active navbar items to highlight at which page you are, see e.g. HydroMT delwaq docs I will create an issue at the pydata theme to see if these can be fixed after which I'm happy to move back to the blue bar.

--pst-color-navbar-link: rgb(237, 237, 255);
--pst-color-navbar-link-hover: #fff;
--pst-color-navbar-link-active: #fff;

[DirkEilander]

see also discussion here: https://github.com/pydata/pydata-sphinx-theme/issues/353 (especially the last comment is of interest)

[JoerivanEngelen]

To be fair, when you click on a page in the navbar in the blue bar theme, e.g. https://deltares.gitlab.io/imod/imod-python/developing.html, the page currently viewed is actually shown in bold, just not as clear as on the HydroMT delwaq docs. By setting these to white, I was able to achieve similar results as in the HydroMT delwaq docs:

iMOD Python adapted:

Delwaq:

This is basically a matter of changing:

.nav-link {
    color: #8486c0 !important;
}

to:

.nav-link {
    color: #fff !important;
}