Right sidebar is missing

[wendigo]

We are trying to update Trino documentation to sphinx-immaterial but we cannot get right sidebar to appear: trinodb/trino#25735

The rendered pages are having right sidebar empty. What can we do to make right sidebar rendered?

[2bndy5]

Looking at the PR changes, I am skeptic of the CSS about list markers. Other than that I don't see any reason why the local page ToC doesn't show.

Your CI is incomprehensible to me. Have you checked the build log for the warnings or errors?

Users sometimes figure out these things on their own when they try to make a smaller sample for reproduction purposes. It would be easier for us to diagnose this if we had a smaller reproduction sample project (.zip file uploaded here or a temporary public repo). The trino project seems rather large and complex, so it seems unrealistic to ask non-team members to investigate a project of that scale.

[wendigo]

There is ./docs/build script that builds documentation using latest sphinx in the docker image

[2bndy5]

Your CI is incomprehensible to me. Have you checked the build log for the warnings or errors?

There is ./docs/build script that builds documentation using latest sphinx in the docker image

This isn't helpful to me because I have no interest in joining the trino team. I was asking if the build logs (output during execution of that script) show any errors or warnings.

It seems like you expect us, a total of 2 people that are not employed by Starburst and hold no responsibilities for the trino project, to inspect the large codebase of the trino project for a very specific unexpected behavior.

What I'm trying to say is that if you want a proper diagnosis, then we need a smaller/simpler sample project that reproduces the issue in question.

---

BTW @XavieLee left us hanging on another possible bug discovered in the same project's doc theme migration. See #445. If @XavieLee has no interest in helping us get to the root of that problem then, they should say so.

[2bndy5]

FWIW, I tried reproducing this using cross refs with the myst-parser,

(test-ref1)=
# Page title

[scroll to title(#test-ref1)

(test-ref2)=
## Heading lvl 2

[scroll to section header](#test-ref2)

but it did not affect the page's local ToC (right side nav menu). In fact, I noticed no unexpected behavior at all.

[XavieLee]

BTW @XavieLee left us hanging on another possible bug discovered in the same project's doc theme migration. See #445. If @XavieLee has no interest in helping us get to the root of that problem then, they should say so.

Hi team, I'm so sorry. I was on a business trip last week. I will share a sample later to help figure out the issue .

[XavieLee]

BTW @XavieLee left us hanging on another possible bug discovered in the same project's doc theme migration. See #445. If @XavieLee has no interest in helping us get to the root of that problem then, they should say so.

Hi team, I'm so sorry. I was on a business trip last week. I will share a sample later to help figure out the issue .

Hi, I share the minimal reproduction in #445 (comment)

[kumiDa]

Thank you @XavieLee !

@2bndy5 , please take a look if this would suffice else I will create a zip with just the doc components like you suggested earlier.

[2bndy5]

I'm looking into it now. Please keep the comments in the appropriate threads.

• left sidebar has unknown icon #445 is what @XavieLee is talking about.
• This thread (Right sidebar is missing #448) seems to have been abandoned by @wendigo. We can't investigate this issue further without a reproducer sample.

[kumiDa]

@2bndy5, Like you pointed out(in #445 (comment)) sphinx-material theme is not being actively maintained and it would be wise to have the trinodb/trino-docs be moved to sphinx-immaterial which is a actively maintained fork of the theme. Hence @wendigo, I would like to work with @2bndy5 on a resolution for this.

@2bndy5, please use the below zip as a reproduced sample for the issue that we are noticing.

trino-476-SANPSHOT-sample.zip

Please note:

• irrespective of whether toc.integrate is included in the html_theme_options.features or not the right sidebar isn't rendering.

[2bndy5]

See #445 (comment).
I think this is related to using myst-parser for everything, especially the toctree directive.

BTW, the author of sphinx-material is likely using this theme for personal projects. In fact, the reason why the version directives (eg versionchanged and deprecated) are styled like admonitions was the result of a feature request from that theme's author.

[2bndy5]

I was able to recreate this issue using pure rst sources. Finally, the page ToC (on right side) appeared when I removed the :titlesonly: option in the root page's toctree directive. I switched back to the markdown sources without the titlesonly option, and the pages' ToC was still rendered as expected.

TBH, I don't think the titlesonly option is applicable to the trino docs because of the way that they are structured. It might have been relevant with sphinx-material theme because this theme takes a different approach to porting the sphinx toc trees into mkdocs toc trees.