Repository navigation
Create a ToC entry for every function, method, class, etc #6316
Description
It would be useful to have an option that causes Sphinx to automatically create a TOC entry for every function, class, and method. (In the absence of this, tables of contents are of limited value).
Activity
Phillip-M-Feldman commentedon Apr 22, 2019
I will try to make this enhancement, but am hoping that someone can point me to the right place in the code.
Phillip-M-Feldman commentedon Jun 8, 2019
What is the target date for the 3.0.0 milestone?
tk0miya commentedon Jun 9, 2019
3.0 will be released in next spring.
pawamoy commentedon Dec 9, 2019
@Phillip-M-Feldman are you still planning to work on this? @tk0miya you added this issue to the 3.0.0 milestone: are you going to implement it?
Phillip-M-Feldman commentedon Dec 9, 2019
pawamoy commentedon Dec 12, 2019
I'm currently writing a plugin for mkdocs with this functionality anyway 🙂
tk0miya commentedon Dec 14, 2019
No, I don't have time for developing 3.0. At present, I'm doing my best to 2.x release.
Phillip-M-Feldman commentedon Aug 17, 2020
What is the relationship (if any) between mkdocs and Sphinx?
Also: I have some time to work this issue, but still need pointers re. where to look in the code.
P.S. I'm surprised that this functionality wasn't built into Sphinx from the start.
pawamoy commentedon Aug 17, 2020
Sphinx and MkDocs both are static site generators if I may say? MkDocs is language agnostic and uses Markdown natively. Other than that there's no relation between the two.
61 remaining items
pradyunsg commentedon Sep 28, 2022
You can also set
toc_object_entries_show_parents = 'hide'if you’d prefer to have shorter names.jakobandersen commentedon Sep 28, 2022
Wait, you can't disable this in any way? That prevents people from upgrading Sphinx unless they redesign their document structures. That sounds like a breaking change that can not happen in a minor release.
pradyunsg commentedon Sep 28, 2022
It's a new feature, which is why it's been added in a new minor version release. I'll point you to an excellent blog post, that I request you read in full.
Whether adding sidebar content when certain themes that don't do the bare-minimum of text wrapping in the sidebars is backwards-incompatible is... well, that's a discussion I'm not going to be a party in. :)
schtandard commentedon Sep 28, 2022
Leaving aside the question of minor/major versions: I was also under the assumption that this would be an optional feature, not a mandatory one. I expect many, many people to be unpleasently surprised if they cannot turn it off.
Is there any reason not to have the old behavior be the default and the new feature be an option?
asmeurer commentedon Sep 28, 2022
I believe reasoning was that we shouldn't add a configuration option for something unless we actually know there will be people who want to turn it off. No one up til now has requested that. I do sort of agree that a theme not handling wrapping isn't a great reason to turn this off (no doubt that can be fixed with a simple CSS change). Such a theme also won't handle a normal header with a long title properly either. Do you have another reason to want to disable it? The only one I can think of is if you already manually added toc entries for each autodoc entry, making this redundant.
I personally think it's fine to make this disableable, but also feel it should continue to be on by default because it's a nice feature for the majority of use cases. A feature that is off by default will only be used by a very small fraction of people who notice the option and turn it on. Sphinx already has too many of these "off by default" nice features IMO.
AA-Turner commentedon Sep 28, 2022
Disabling the feature currently is not supported. A PR to add support would be considered, but the default would remain as current (domain objects in the table of contents).
As a workaround to disable support, you can patch the
_toc_entry_namemethod in your extension orconf.py(untested):A
josephmure commentedon Sep 29, 2022
A custom version of the "sphinxdoc" theme, but I get the same problem with the vanilla "classic" theme (see picture below).
If a horizontal scrollbar is needed to actually see the method name, most users will not bother and will rather search through the main page rather than the sidebar.
I am aware of this. Although using it can avoid the rendering error if method names are not too long, I would prefer not to have method names in the ToC at all because they are redundant: there is already a method list in the page (see picture below).
The problem does not seem to be text wrapping in general: as you can see in the picture below, the class name itself is also long, but gets wrapped. Only method names (perhaps because of the particular font that is used) are not.
I do not understand this line. What should I add in
conf.pyexactly?jakobandersen commentedon Sep 29, 2022
It is indeed a feature, but it fundamentally changes the structure of documents compiled with it. From the perspective of a user that has designed their document without this feature in mind (implicitly that's all Sphinx < 5.2 users), it is breaking their document.
The hackish workaround is fine for now, but there really should be a proper option. That is, at least I request this feature.
AA-Turner commentedon Sep 29, 2022
Please see #10886 (intended for 5.2.3) for an option for global control and a new
nocontentsentryflag (as requested by @jakobandersen)A
Change Sphinx docs theme to Furo
Change Sphinx docs theme to Furo
AA11BB22 commentedon Oct 20, 2022
Can be this feature be extended to support other domains (non-Python domains ... namely C++ domain)?
hagenw commentedon Oct 21, 2022
The text for the main heading gets wrapped because it is text whereas the new entries are added as
<code></code>to the TOC whichprovidesprevents wrapping in most themes and can also lead to strange font sizes, e.g.Another problem is that a lot of users have started to add headings to the docs as the new TOC feature was missing for years and also to have a better separation on the page:
With the new feature you have the entries repeated in the TOC, one for the heading and one for the code entry as is present in both examples shown here.
So it's indeed a relative big change and should have an option to disable it as it now has since version 5.2.3.
Workaround sphinx-doc/sphinx#6316