trino
Switch documentation theme to immaterial (w/ support for dark mode)
#25735
Open
Switch documentation theme to immaterial (w/ support for dark mode) #25735
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
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.
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!!
Hi @kumiDa , the right sidebar can not show under this theme on my side, are u meet the same issue?
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.
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.
@kumiDa NICE!
I'm adding sphinx image to docker-images: trinodb/docker-images#236
Hi @kumiDa I mean this icon issue, u can check it under
function and operators.
@kumiDa Do u have icon issue on left sidebar? An additional icon will be displayed.
@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, 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?
@nineinchnick ptal
Rebased and solved conflicts. 115 release is ongoing so this is suppose to fail (I'll retrigger build once release is done)
wendigo
changed the title
I've fixed a little problem with code highlighting (white dots due to a border radius in the dark mode)
I only found two issues. The first one is the left navbar has different styles:
- open the top section page:
- 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).
@nineinchnick can you test in the https://wendigo.pl/trino-docs/ ?
It remembers settings when hosted.
@nineinchnick I've made small change, Idk whether it's better: https://wendigo.pl/trino-docs/optimizer/statistics
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.
@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.
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.
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.
It's fine for me, all tables have a font of 14px, both headers and content. Regular text is 17px.
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.
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.
Right sidebar is still missing. I tried to figure this out but no luck
@mosabua i don't think this is it
Well... it muse be supported somehow - see https://sphinx-immaterial.readthedocs.io/en/latest/apidoc/format_signatures.html
Also .. maybe https://jbms.github.io/sphinx-immaterial/customization.html#filemeta-hide-toc is set?
Update sphinx theme to sphinx-immaterial
Update style to present unbulleted toctree lists
Update configuration to fix file view & edit links
Update configuration to remove irrelavent version listing configs
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
Login to write a write a comment.
Description
sphinx-immaterialtheme.Additional context and related issues
sphinx-materialtheme repo at 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-immaterialtheme is being actively maintained unlike thesphinx-materialtheme repo that isn't seeing active code updates.Release notes
(x ) Release notes are required. Please propose a release note for me.