Switch documentation theme to immaterial (w/ support for dark mode)

[kumiDa]

Description

• The contents of the PR introduces the feature requested in Support Light/Dark Mode Toggle for Documentation #25719
• Configuration and respective setup files are update to use sphinx-immaterial theme.
• Styling files are amended to use the theme customization options provided by the theme to achieve the same look and feel as before while introducing the light/dark toggle feature.
• Local TOCtree is displayed in the left sidebar
• The theme can be toggled between the following modes
  • Auto mode: as per browser setting
    
  • Light mode
    
  • Dark mode
    

Additional context and related issues

• Why the choice of sphinx-immaterial?
  • As can be inferred from this discussion on sphinx-material theme repo at Optional dark theme bashtage/sphinx-material#89, there's a fork of this theme which includes this light/dark toggle feature- https://jbms.github.io/sphinx-immaterial/
  • sphinx-immaterial theme is being actively maintained unlike the sphinx-material theme repo that isn't seeing active code updates.

Release notes

(x ) Release notes are required. Please propose a release note for me.

[kumiDa]

Note to the reviewers, the docker image used in the CI to validate this PR has to be updated to include the new sphinx-immaterial theme

[nineinchnick]

I'm very excited about using this new theme because it supports Mermaid charts, and we could use to make some doc pages easier to understand.

[kumiDa]

I'm very excited about using this new theme because it supports Mermaid charts, and we could use to make some doc pages easier to understand.

Would love to work with the team in this effort too!!

[XavieLee]

Hi @kumiDa , the right sidebar can not show under this theme on my side, are u meet the same issue?

[XavieLee]

btw, this theme still in beta, it has some UI bugs like sidebar, icon, css etc,

So we may explore other themes, and consider using sphinx-immaterial when it is ready.

[kumiDa]

btw, this theme still in beta, it has some UI bugs like sidebar, icon, css etc,

So we may explore other themes, and consider using sphinx-immaterial when it is ready.

This behaviour is due to the use of following configuration toc.sticky which is detailed in https://jbms.github.io/sphinx-immaterial/customization.html#configuration-options as :

toc.sticky

Makes headings in the left and right sidebars “sticky”, such that the full path to each heading remains visible even as the sidebars are scrolled.

I've removed this config in 083720e, as keeping the TOC sticky was anyways not supported in Trino 475-SNAPSHOT Documentation

Now the UI issue noticed is resolved.

[wendigo]

@kumiDa NICE!

[wendigo]

I'm adding sphinx image to docker-images: trinodb/docker-images#236

[XavieLee]

Hi @kumiDa I mean this icon issue, u can check it under function and operators.

[XavieLee]

@kumiDa Do u have icon issue on left sidebar? An additional icon will be displayed.

[kumiDa]

@kumiDa Do u have icon issue on left sidebar? An additional icon will be displayed.

@XavieLee, thanks for checking this.

This is intended more a feature than an bug, as documented here - https://sphinx-immaterial.readthedocs.io/en/latest/apidoc/index.html#objconf-toc_icon_class

This TOCtree is consistent with changes made in 2ca072b

[XavieLee]

Yes, I found the reason and fixed it already. Thank u! @kumiDa

BTW, why don't you upgrade to the latest version?
I upgrade it and keep the necessary configuration, u can refer to it if you need. #25733

[kumiDa]

BTW, why don't you upgrade to the latest version? I upgrade it and keep the necessary configuration, u can refer to it if you need. #25733

@XavieLee, Thanks for the suggestion. Which version are you suggesting about? I didn't quite understand what you are referring to here.

[XavieLee]

@XavieLee, Thanks for the suggestion. Which version are you suggesting about? I didn't quite understand what you are referring to here.

@kumiDa I mean using sphinx==8.2.3. Since we have changed the theme to sphinx-immaterial and use its latest version, sphinx can also be upgraded together. After testing, the latest version works well and does not require much change. What do you think?

[wendigo]

@nineinchnick ptal

[wendigo]

Rebased and solved conflicts. 115 release is ongoing so this is suppose to fail (I'll retrigger build once release is done)

[wendigo]

115 release: https://github.com/trinodb/docker-images/actions/runs/14988068787

[nineinchnick]

I only found two issues. The first one is the left navbar has different styles:

1. open the top section page:
   
2. open any subsection:
   

The second issue is that it detects my system preferences, but doesn't remember if I switch the theme manually. Maybe this is caused when opening it locally. It looks like it remembers the setting per page, not the whole site.

I like how tables use a more compact font. Syntax highlight and note/warning boxes look great. It also looks fine in responsive mode (on mobile).

[wendigo]

@nineinchnick can you test in the https://wendigo.pl/trino-docs/ ?

[nineinchnick]

It remembers settings when hosted.

[wendigo]

@nineinchnick I've made small change, Idk whether it's better: https://wendigo.pl/trino-docs/optimizer/statistics

[nineinchnick]

It's better, we can merge it like this. I'll post it on Slack to give others a chance to take a look, since this change has a very high impact.

[kumiDa]

@nineinchnick can you test in the https://wendigo.pl/trino-docs/ ?

Thanks for hosting this @wendigo to test the changes. I was able to verify the changes I expected.

[kumiDa]

I've fixed a little problem with code highlighting (white dots due to a border radius in the dark mode)

Ah! The code blocks look clean now.

[kumiDa]

I like how tables use a more compact font. Syntax highlight and note/warning boxes look great. It also looks fine in responsive mode (on mobile).

@nineinchnick , how do you feel about the table headings? I kind of felt they are unintuitively smaller in font than the Table content.

[nineinchnick]

It's fine for me, all tables have a font of 14px, both headers and content. Regular text is 17px.

[mosabua]

Great work on this PR so far @kumiDa .. sorry I have not been able to help. Please ensure that the look and feel for the default remains as unchanged as possible or is definitely a listed and known improvement.

I just had a very short look - the ToC sections now have bullets.. these should be removed - compare https://trino.io/docs/current/ and https://wendigo.pl/trino-docs/ .. I hope to be able to look some more later this week.

[mosabua]

I just noticed that the right hand navigation for each page also seems to be gone. We definitely need that .. there are some very long pages and without that nav it is very hard to find things.

[kumiDa]

the ToC sections now have bullets.. these should be removed

Thanks for reviewing the changes @mosabua!

The changes to retain the unbulleted toctree listing is made in 965166e

[wendigo]

Right sidebar is still missing. I tried to figure this out but no luck

[wendigo]

@mosabua i don't think this is it

[mosabua]

Well... it muse be supported somehow - see https://sphinx-immaterial.readthedocs.io/en/latest/apidoc/format_signatures.html

[mosabua]

Also .. maybe https://jbms.github.io/sphinx-immaterial/customization.html#filemeta-hide-toc is set?

[wendigo]

It seems to me that switching to immaterial is not an option as it breaks too many thing and we are getting little in return

Stale

[kumiDa]

@mosabua, the right side local TOCs are now visible through this commit 3339b50.

Please share your reviews.