docs: add dark mode

[laurenceisla]

Adds dark mode to the documentation using sphinx-rtd-dark-mode.

[laurenceisla]

Testing to see how it looks. The code blocks may look a bit too clear compared to the rest of the page.

[steve-chavez]

Looks cool!

The code blocks may look a bit too clear cojpared to the rest of the page.

Yeah, everything looks good except the snippets

[wolfgangwalther]

The different logos on the index page look a bit inconsistent as well...

[laurenceisla]

The different logos on the index page look a bit inconsistent as well...

Yeah, I modified the logos that have white background and added a white border only to the letters. Looks better, but not sure what you think. It may be modified in another PR too.

There are also problems with the generated images, e.g. in tutorial 0 there are black arrows and letters that are not readable at all. A white border for those elements or a white background for the whole image (easier) is needed.

[steve-chavez]

Yeah, I modified the logos that have white background and added a white border only to the letters. Looks better, but not sure what you think. It may be modified in another PR too.

I like it. And yeah, things can be improved on another PR. Perhaps open new issues for those.

[wolfgangwalther]

Yeah, I modified the logos that have white background and added a white border only to the letters. Looks better, but not sure what you think.

You can't just modify the logos like that, those are part of a corporate identity. Those sponsors might actually have different logos for a dark background, for example just going to supabase.com and neon.tech, immediately shows me that both must have a variant for dark background, too.

Edit: Tembo, too, from first glance. But ultimately, you'd have to ask every one of them whether they have a different logo for dark background.

[laurenceisla]

I was hoping to not change the logo itself by adding a bit of background, but yeah it changes the silhouette too much.

Tembo, too, from first glance

IIRC that logo ls meant for both dark/light mode.

But yes, the sponsors have the last saying in this, I'll notify them to provide a dark-mode logo. Since it would take some time I'll remove that commit and merge as-is for now.

[wolfgangwalther]

Since it would take some time I'll remove that commit and merge as-is for now.

Is there any time-pressure in getting a dark theme out? Why not just wait until you have the logos?

[wolfgangwalther]

Most importantly: Have you confirmed that you can actually use different logo files with both theme variants? IIRC, you had used the same, modified, file with your last try, right?

[laurenceisla]

Most importantly: Have you confirmed that you can actually use different logo files with both theme variants?

Ah, yeah, was just looking to see if that's possible at all. It seems to be by ditching ..image and using raw html, or by using javascript and ..figure, but it's not that straightforward for both cases.

If it can't be done, then adding a white background like Supabase or Neon is using right now would be a way out to keep them kinda consistent... anyhow, the sponsors need to approve them too.

Is there any time-pressure in getting a dark theme out? Why not just wait until you have the logos?

Nope, was just my way to stop the PR from staying in limbo for too long, since I don't actually mind the inconsistency of the logos that much.

In summary, this needs to be done:

• Check if it's feasible for the logos to change for each theme and ask the sponsors to provide dark mode logos
• Otherwise, ask if it's OK to sponsors to use white background for logos (maybe they provide one for both dark/light modes), this would be easier.

[wolfgangwalther]

Nope, was just my way to stop the PR from staying in limbo for too long, since I don't actually mind the inconsistency of the logos that much.

I wouldn't mind the inconsistency temporarily, if I knew that it would be possible to easily fix it later on. But I would not want to be stuck with it for technical reasons.

In summary, this needs to be done:

I'm not exactly sure how PostgREST/postgrest-docs#628 would work out, but this could potentially work around the issue, if the landing page was always the same style and only the docs itself would be switched to dark? Then we'd just need to put the sponsors' logos on the landing page - done.

[laurenceisla]

... this could potentially work around the issue, if the landing page was always the same style and only the docs itself would be switched to dark?

Ah, I forgot about the landing page. Yes, that would be a good workaround actually.

But I would not want to be stuck with it for technical reasons.

Now that I was checking around, there are some themes different from rtd that look good and give many out of the box solutions. For example, Furo seems to be a good alternative, it even has selecting image by dark/light theme and is compatible with all the extensions we use right now (except sphinx-tabs, but has an alternative) and looks easier to customize. The documentation for PIP uses this theme.

The drawbacks are that there may be some issues that would come back like PostgREST/postgrest-docs#351 and some features may be missing, like the breadcrumb.

Just to get the idea out there.

[wolfgangwalther]

Now that I was checking around, there are some themes different from rtd that look good and give many out of the box solutions.

Would they work with readthedocs, though? Readthedocs adds this little box on the bottom left to select versions of docs etc. - that's nothing we actually build with sphinx. So I'm not sure how a different theme would work together with that.

[laurenceisla]

Would they work with readthedocs, though?

Didn't check if it was straightforward enough, but I'm pretty sure it can be done since the Pip docs have that button enabled.

[laurenceisla]

I installed the Furo theme to see how it looks like. The RTD button is activated without problems. It still needs some tweaks and the sidebar doesn't fully convince me, but the navigation using the right panel looks really good.

[wolfgangwalther]

It still needs some tweaks and the sidebar doesn't fully convince me, but the navigation using the right panel looks really good.

I agree. It doesn't convince me, but the right panel is cool. I think the pip docs look good with it.. but ours not really.

Overall.. a 👎 from me right now. But maybe the "tweaks" you have in mind would change that, not sure. My gut feeling tells me that there would be more than just some "tweaks" needed here... ;)

[laurenceisla]

My gut feeling tells me that there would be more than just some "tweaks" needed here

True that, I noticed there are some other things that are not trivial to adapt. Well, at least we know that themes can be used if we need them in the future. For now, I'll go back to sphinx-rtd-dark-mode.

The good thing is there was an easy way to change images according to the theme. Basically hide/show the <img> element using css display property. As an example, I used a dark mode image provided by Supabase in their webpage. It's still pending to ask the other sponsors for their logos, but it can be done later.

Also added some background to the other transparent images to make them readable at least.

Edit: Neon dark mode logo added. I'm asking the other sponsors for their logos.

[laurenceisla]

OK, this should be officially completed. All the sponsors that did not provide a dark mode before were contacted. Most of them sent the dark mode logo and others confirmed that the logo is OK for both dark and light mode. Also updated the light mode logos with new ones for those who requested it.

[laurenceisla]

The sphinx-rtd-dark-mode is already merged to Nixpkgs as mentioned in #3289 (comment). Will take a while to use that pkgs version, so I'm merging as it is right now.