Create a ToC entry for every function, method, class, etc

[Phillip-M-Feldman]

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).

[Phillip-M-Feldman]

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]

What is the target date for the 3.0.0 milestone?

[tk0miya]

3.0 will be released in next spring.

[pawamoy]

@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]

I did spend some time on this, but wasn't able to figure it out. I will likely try again within the next few weeks.

…

On Mon, Dec 9, 2019 at 4:52 AM Timothée Mazzucotelli < ***@***.***> wrote: @Phillip-M-Feldman <https://github.com/Phillip-M-Feldman> are you still planning to work on this? Why are you asking about the 3.0.0 milestone? Has it been implemented already? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#6316?email_source=notifications&email_token=AAIEDRDSU4ALMXRU2RFWLG3QXY5RNA5CNFSM4HHS4DW2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEGJCBGY#issuecomment-563224731>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAIEDRFBP5Q3OFA54VATFXDQXY5RNANCNFSM4HHS4DWQ> .

[pawamoy]

I'm currently writing a plugin for mkdocs with this functionality anyway 🙂

[tk0miya]

No, I don't have time for developing 3.0. At present, I'm doing my best to 2.x release.

[Phillip-M-Feldman]

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]

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.

[Phillip-M-Feldman]

Thank you! I think that I will stick with Sphinx, despite some severe limitations, because of its Python-centric approach.

…

On Mon, Aug 17, 2020 at 12:51 PM Timothée Mazzucotelli < ***@***.***> wrote: Sphinx ans 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. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#6316 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAIEDRHHLSLADXSYYIANOB3SBGC4PANCNFSM4HHS4DWQ> .

[alexisrolland]

I'm voting up for this feature. It seems essential to me.

[AA-Turner]

Sphinx 5.2.0 has been released incorporating this feature.

A

[tony]

@AA-Turner Looks good, thank you!

Settings options:

• add_function_parentheses = False (default: True)
• toc_object_entries_show_parents can be (default: 'domain'):
  • toc_object_entries_show_parents = 'domain'
  • toc_object_entries_show_parents = 'hide'
  • toc_object_entries_show_parents = 'all'

Example on Sphinx 5.2 w/ Furo theme (screenshot)

My settings:

toc_object_entries_show_parents = 'hide'

URL: https://libvcs.git-pull.com/sync/git.html (may break in future, sorry!)

[josephmure]

Is it possible to disable this feature? It messes up the rendering of a project I work on:

https://openturns.github.io/openturns/master/user_manual/_generated/openturns.ConditionalDistribution.html

Here is how it normally looks:

https://openturns.github.io/openturns/1.19/user_manual/_generated/openturns.ConditionalDistribution.html

Using the hide option makes it a little better, but does not restore the old look:

[AA-Turner]

What theme are you using? I'd suggest this is more a theme error with not handling long ToC entries -- a horizontal scrollbar would be more useful here.

A

[pradyunsg]

You can also set toc_object_entries_show_parents = 'hide' if you’d prefer to have shorter names.

[jakobandersen]

You can also set toc_object_entries_show_parents = 'hide' if you’d prefer to have shorter names.

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]

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]

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]

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]

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_name method in your extension or conf.py (untested):

PyObject._toc_entry_name = lamba signode: ''

A

[josephmure]

What theme are you using? I'd suggest this is more a theme error with not handling long ToC entries --

A custom version of the "sphinxdoc" theme, but I get the same problem with the vanilla "classic" theme (see picture below).

a horizontal scrollbar would be more useful here.

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.

You can also set toc_object_entries_show_parents = 'hide' if you’d prefer to have shorter names.

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).

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. :)

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.

As a workaround to disable support, you can patch the _toc_entry_name method in your extension or conf.py (untested):

PyObject._toc_entry_name = lamba signode: ''

I do not understand this line. What should I add in conf.py exactly?

[jakobandersen]

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]

Please see #10886 (intended for 5.2.3) for an option for global control and a new nocontentsentry flag (as requested by @jakobandersen)

A

[AA11BB22]

Can be this feature be extended to support other domains (non-Python domains ... namely C++ domain)?

[hagenw]

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.

The text for the main heading gets wrapped because it is text whereas the new entries are added as <code></code> to the TOC which provides prevents 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.