config to control the toc depth for a page and/or project

[cjw296]

Is your feature request related to a problem? Please describe.
From pradyunsg/furo#557:

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.

Describe the solution you'd like

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

Describe alternatives you've considered

toc_object_entries worked in this case but it's a shame it's a boolean rather than a depth: I would have preferred to include class names, but not methods within those classes.

[cjw296]

@tk0miya / @AA-Turner - thoughts on this? I'm happy to do the work for a PR if it's likely to be merged. Just hit this again on https://sybil.readthedocs.io/en/latest/api.html where the right nav is also becoming unusable: I want to list functions, module-level attributes and classes in the right nav, but not class attributes or methods.

[yuvaltassa]

We would love this feature too!

Our API reference page has an unusably large right nav, but we really don't need the L3 items, and they are already grouped nicely.

[cjw296]

@yuvaltassa - you can turn them off completely, but certainly for my case, I want the top-level ones to be there (mainly classes, sometimes function or module-level variables) just not methods or attributes of classes.

[yuvaltassa]

Sorry, by "we really don't need the L3 items", I meant that we would like to turn off TOC indexing for items with depth >= 3, but leave the other items (depth < 3) in the TOC. Are you saying that this is something I can already do?

[cjw296]

No, the toc_object_entries conf.py setting is boolean: they're either all there or none of them are there, so we do both want the same feature :-)

[yuvaltassa]

@cjw296, if you get around to writing that PR, we'd love to help you test it 🙂

[mgeier]

This might be a theme-related setting.

Sphinx's built-in themes already provide a globaltoc_maxdepth theme option: https://www.sphinx-doc.org/en/master/usage/theming.html?highlight=globaltoc_maxdepth#builtin-themes
Some external themes also inherit this theme option (I just tried it with my own insipid theme), but the furo theme seems to handle the TOC differently.

I think this should be a feature request for the furo theme (but it seems the maintainer isn't really thrilled about it: pradyunsg/furo#557).

[mgeier]

There might be one thing for Sphinx to do though: AFAICT, currently the :maxdepth: option of the toctree directive doesn't affect the display of object entries ... right?
Maybe it should do this?

[cjw296]

@mgeier - not sure I agree, this code is under recent development, see 650f63b from Sept 2022. We have a toc_object_entries boolean for turning object entries on/off and now a :nocontentsentry: option, but what we need is a way to say "in the Python domain, I only want top-level objects listed in the ToC". So, modules-level variables, classes themselves and functions but not class methods, attributes, etc.

It may even be sufficient to just have a "toc_object_no_class_members" setting, which would certainly give me what I need. Would be helpful to have @AA-Turner's thoughts on this...

[mgeier]

@mgeier - not sure I agree

You don't have to, but maybe I can clarify a bit:

My comments were in response to the issue title "config to control the toc depth for a page and/or project": such a control already exists in the built-in themes (globaltoc_maxdepth) and it seems to be lacking in furo.

The top comment then bring another idea into play: "I would have preferred to include class names, but not methods within those classes." In this case I agree, this could also something that sphinx could provide.

However, those are two orthogonal settings and should not be conflated.

To recap: there are three potential ways to influence the appearance of TOC levels:

• One already exists with globaltoc_maxdepth in the built-in themes, but is lacking in furo. No change needed in Sphinx.
• Another exists via the :maxdepth: option of the toctree directive, but this doesn't seem to work with object entries
• And yet another could be added as option directly to the class/module definitions to control whether members etc. should be shown.

The first two specify an explicit "depth", the third only indirectly affects the TOC depth.

[cjw296]

Right, so it seems I have two potential feature requests for Sphinx:

1. Make the :maxdepth: option of the toctree directive apply to object entries
2. Added an toc_ option to control whether class members are included in the object TOC entries.

I'd have a preference for the second one, I guess we wait to hear from @AA-Turner before I do any PR work...

[pradyunsg]

My comments were in response to the issue title "config to control the toc depth for a page and/or project": such a control already exists in the built-in themes (globaltoc_maxdepth) and it seems to be lacking in furo.

I think you're misunderstanding what this request is about. This user is asking for a limit on toc (i.e. in-page navigation), not toctree (i.e. site-wide navigation, assuming titles_only is passed). The maxdepth mechanisms you've mentioned apply to toctrees, not toc.

[cjw296]

@pradyunsg - right, that's what I thought, so I guess the subject for this feature request is correct and remains the way forward: domain objects were only added to the toc in 5.2.0, but the config added as part of that was a boolean "all included" or "none included".

So it seems we're back to:

1. Added a toc_ option to control whether class members are included in the object TOC entries.

2. Added a toc_ option to control the depth of object TOC entries added relative to the page they're in.

I'm fine with either, and happy to do the work for the PR, but will wait to hear from folks if it's a thing that's likely to be merged, preferably in the 5.x line of Sphinx...

[sneakers-the-rat]

fwiw, came across this while googling, not sure why it wasn't mentioned but within a page you can control the depth of the in-page toc by using :tocdepth: at the top of the file: https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html#file-wide-metadata