Automatically collapse items in right sidebar

[kevinzakka]

Hi @pradyunsg, apologies for all the questions! Curious what would be the easiest way to add "expand" buttons to the right sidebar and not have it automatically list out everything in the page?

See here for example: https://mujoco.readthedocs.io/en/latest/APIreference.html

We recently switched to furo and for some of these longer pages, scrolling through the right sidebar to find something requires a lot of scrolling. In the previous theme, it was automatically collapsed and you had to explicitly expand it.

[pradyunsg]

Furo doesn't provide any way to do that. (update: Sphinx does!)

My typical suggestion for such pages is to break them up. If you're struggling to navigate the page with the right sidebar, that's a symptom of too-much-content on the page. I think it's better to solve the problem by restructuring the content into sub-pages and creating a section instead.

Having too-long pages has multiple negative effects in my experience (off the top of my head: longer page load times on slow connections, worse navigabilty within the documentation overall, worse search results from within Sphinx, worse SEO from broader search engines since the page has "less focus", and more scrolling to get to where you want to go because the right sidebar isn't useful). IMO adding complexity for tweaking behaviours of the right sidebar isn't worthwhile -- it's a symptom of a problem and doesn't help with solving the problem. :)

See https://pip.pypa.io/en/stable/user_guide/ for an example, although that has more prose than reference and it's been moving into a different (new) section https://pip.pypa.io/en/stable/topics/ since it was... uhm... really long. See also https://pip.pypa.io/en/stable/reference/build-system/ for a different example of an "it was too much as a single page" that I've broken up into three smaller more-focused pages.

PS: A bunch of styles in https://github.com/deepmind/mujoco/blob/main/doc/css/theme_overrides.css are non-functional within Furo. It's not harmful but might be worth trimming to make it easier to modify in the future (IIUC, you've moved from sphinx-rtd-theme, which is where those overrides are coming from).

[kevinzakka]

This is super helpful, thanks @pradyunsg! It makes perfect sense to break up API reference, you're absolutely right :) Thanks for the useful example links as well. Cheers!

[pradyunsg]

Adding a reference to #566 (comment) since it solves this via Sphinx's configuration knobs.

[pradyunsg]

FWIW, I'm open to a discussion about potential usecases where breaking up a page into smaller pages isn't a good idea -- I haven't come across any pages with such a constraint myself, so I don't know much about that usecase.

And I don't wanna try designing a solution for a usecase I don't understand. :)

[pradyunsg]

#566 (comment) resolves this concern.