How can I limit the right-nav depth?

[cjw296]

For one of my projects, the right nav for the API reference has become unusable: it lists sections in the .rst file, then class names, then methods on those classes, all in the right nav.

What I'd like to do is limit the depth on the right name, so only the section heading and class names are shown.

How do I do that?

[pradyunsg]

Furo doesn't support any way to "hide" content from the right sidebar. It merely presents and styles the output from Sphinx for that.

See the toc_* configuration variables in Sphinx for some of the their toc controls: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-toc_object_entries

[pradyunsg]

furo/src/furo/theme/furo/page.html

Line 198 in 93e0093

{{ toc }}

Uses the toc context variable provided directly by Sphinx.

[yuvaltassa]

@cjw296 we also want to do this.
Did you figure it out?
Any helpful pointers?
Cheers

[cjw296]

@yuvaltassa - the code in Sphinx is surprisingly recent, only added last year I think.
I've got a feature request open here, probably best to subscribe to it and +1 my comment or some such.

[cjw296]

@pradyunsg - @mgeier suggests in sphinx-doc/sphinx#10935 (comment) that Furo may want to grow a globaltoc_maxdepth option, is that suitable for a feature request?

[pradyunsg]

No, that's unrelated. And, Furo isn't going to grow an option to enable hiding content based on depth from the left sidebar -- showing the entire site structure is an intentional design choice.

[pradyunsg]

FWIW, I've said this elsewhere: if you feel an urge to do this, the underlying problem might be that you have much content on the page.

#584 (comment) has the fuller comment.

[yuvaltassa]

@pradyunsg you are not wrong. We've taken your advice to heart and are looking into breaking up our too-long page.

But this request is different and would be relevant even after we did that.

It is sometimes the case that you have lots of very small items that each deserves its own anchor, mostly so it can be refered to from elsewhere, but too small to deserve a TOC link.

As an example, consider our XMLreference page. We are actually really happy with the way it is rendered at the moment, the right nav is a bit large but not unmanageably so. However, this is only because we are only referencing XML elements and not XML attributes (marked in red if you scroll down). We really want to add attribute links so we can link to them more precisely, but we don't want these links in the right nav TOC.

To sum up, I completely agree with your comment, and breaking up long pages is indeed good practice, but this does not render invalid the request @cjw296 and I are making, that some levels of depth can, in some circumstances, be inappropriate for the TOC, even if they do have anchors.

Does that make sense?

[cjw296]

@pradyunsg - in my case, I've hit this only in the API reference of projects. These documents are intentionally TOC-dense and contain all the objects in the project; for this reason the right-nav is actually really important here, and having finer-grained control over what is and isn't included there would be really helpful.

[pradyunsg]

Adding a link to #566 (comment) for this.