Open cjw296 opened 2 years ago
@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.
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.
@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.
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?
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 :-)
@cjw296, if you get around to writing that PR, we'd love to help you test it :slightly_smiling_face:
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: https://github.com/pradyunsg/furo/discussions/557).
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?
@mgeier - not sure I agree, this code is under recent development, see 650f63b9f77f87c9097e725059de036f93ba9d5b 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 - 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:
globaltoc_maxdepth
in the built-in themes, but is lacking in furo
. No change needed in Sphinx.:maxdepth:
option of the toctree
directive, but this doesn't seem to work with object entriesThe first two specify an explicit "depth", the third only indirectly affects the TOC depth.
Right, so it seems I have two potential feature requests for Sphinx:
:maxdepth:
option of the toctree directive apply to object entriestoc_
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...
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 infuro
.
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 toctree
s, not toc
.
@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:
Added a toc_
option to control whether class members are included in the object TOC entries.
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...
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
Is your feature request related to a problem? Please describe. From https://github.com/pradyunsg/furo/discussions/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.