Allow adding **local** table of contents without the error message

[Jackenmen]

Is your feature request related to a problem? Please describe.
I understand that it doesn't make much sense to have a full table of contents as furo already shows full ToC on the sidebar and I'm assuming this is why such an error message exists, but I don't think those reasons are as valid for the local table of contents. A local table of contents can be useful to, for example, list the options available to the user more clearly.

Describe the solution you'd like
I think hiding the message only for the local table of contents would be a great solution to this problem.

Describe alternatives you've considered
If you don't agree that having a local table of contents can be useful then a possible alternative would be to have a theme setting that you have to opt into to disable the error (fully or just for the local table of contents, whatever is easier or is of your preference).

Additional context
Links to some examples of docs pages where we would like to use the local table of contents:
https://red-discordbot--4675.org.readthedocs.build/en/4675/install_windows.html

https://red-discordbot--4675.org.readthedocs.build/en/4675/install_linux_mac.html

[pradyunsg]

Hi! Thanks for filing this issue, and for a really well written description! ^>^

As you've correctly inferred, this is an intentional choice to prevent folks from using the contents directive when the right sidebar provides this information already. I think local ToCs should be disallowed for the same reasons -- it is still duplicating information presented in the sidebar; albeit a smaller subset of the same.

Is there a specific reason you want to nudge users with a local ToC instead of something like https://pip--9474.org.readthedocs.build/en/9474/getting-started/#supported-installation-methods?

To set expectations early, I am being exceeding cautious about adding configuration options to this theme -- each added configuration option is more complexity in the theme for me to check and keep functional. I don't think this crosses that bar (that might change based on your response to the above question 😉) but, I'm definitely not enabling this for page-wide ToC.

[Jackenmen]

Is there a specific reason you want to nudge users with a local ToC instead of something like https://pip--9474.org.readthedocs.build/en/9474/getting-started/#supported-installation-methods?

If I'm understanding correctly, the linked documentation page is similar to my documentation pages, but the difference is that it needs to be written manually. In the project I linked, I could definitely use this as a nice workaround for the errors shown by furo, but I don't think it's ideal as it requires me to maintain the list of methods (or operating systems in the second link) separately rather than have Sphinx generate it automatically for me. It's not a huge deal since those sections rarely change (the list of the operating systems probably can change somewhat more often as new versions of OSes are made and the older reach their EOL), but it does sound like an unnecessary hassle to keep the list of links up-to-date when Sphinx can easily generate it for me.

As for why I/we think it's better to keep the local ToC rather than leave it to the full ToC on the sidebar is mostly due to the experience we have with the end-users we get/target. We have a lot of users who don't have a lot of experience with programming or command line, and while you can probably still expect most of those users to correctly choose the install method or operating system they want to see commands for, we still do get users who may, for example, not notice they're using install instructions for a different version of their operating system (or maybe even different distribution/operating system, although I would need to do a bit of search on that to make sure) or not notice that there even is a section for their operating system. I expect that some of these users may notice the full ToC on the sidebar, but I still suspect not all of them will.

We're trying to be as accessible as we can and for this kind of users, we carefully try improving how our docs look, to make sure that as many people can correctly follow the steps. And considering that we have volunteers helping users and those volunteers have limited time, it's really important for us to have the documentation do most of the work that these volunteers will otherwise have to (well, not "have to" as obviously it's voluntary work, but I assume you'll understand what I mean here) assist with.

Anyway, maybe I digressed a bit but TL;DR is that IMO local ToC lists the available options more clearly than the sidebar that is away from content and while the linked pip documentation can be a good workaround, it would require a bit more maintenance work than auto-generated local ToC.

[pradyunsg]

Hmm.. Thanks for a detailed response! To me, an important difference between the two is, that in the link I posted, the section listed/duplicated the same options as the ToC and utilised the flexibility (of not needing to use the same text as the section-title) to provide more context to help the user decide between their options. :)

I do have one follow up question: if the main goal is to reduce duplication and potential for confusion for end users, would something like sphinx-inline-tabs be a better fit for such content; preventing the user from seeing the wrong set of instructions entirely?

[Jackenmen]

would something like sphinx-inline-tabs be a better fit for such content; preventing the user from seeing the wrong set of instructions entirely?

Hmm, this seems like a good idea for the first document I linked:

However, I don't really think it's gonna work for the Operating systems in the second document, as there's just too many of them to look good with tabs:

// side thought: it would be cool if choosing specific tabs could show/hide some section of the docs that is further in the document 👀

Using tabs also wouldn't allow us to link to the section for the specific operating system as the anchor links don't work with tabs.

[jackbentley]

Unsure if the extension supports it. However, you may be able to use tabs inside tabs. So break it down into Windows, Linux, Mac then under Linux have the various distros under it. You could even go further and break it down to 3 levels with Linux > CentOS/RHEL > 7.

That being said, I have seen large quantities of tabs like that before and it looks fine to me. It allows you to glance at what is supported and not have to scroll through lots of unrelated junk.

Not sure what you mean about anchor links - do you have an example for context so I can give a suggestion?

[Jackenmen]

Unsure if the extension supports it. However, you may be able to use tabs inside tabs. So break it down into Windows, Linux, Mac then under Linux have the various distros under it. You could even go further and break it down to 3 levels with Linux > CentOS/RHEL > 7.

Nope, it doesn't: pradyunsg/sphinx-inline-tabs#9

That being said, I have seen large quantities of tabs like that before and it looks fine to me. It allows you to glance at what is supported and not have to scroll through lots of unrelated junk.

Local ToC can do that too 😇
I don't know, I just don't think it looks that great design-wise even though the tabs themselves still work the same as they do with a smaller amount of tabs.

Not sure what you mean about anchor links - do you have an example for context so I can give a suggestion?

I meant anchor links to specific sections that make the browser to automatically "jump" to it, such as:
https://red-discordbot--4675.org.readthedocs.build/en/4675/install_linux_mac.html#opensuse-leap-15-1

This does not work with the sphinx-inline-tabs extension.

[pradyunsg]

Alrighty! Color me convinced that folks who know when this is useful should still be able to use local ToCs. However, I'm still very much against allowing folks to be able to do this without much thought on their end.

So, here's my plan: I'll add an escape hatch for this but I don't intend to add any additional CSS to make the ToC look nicer when using this escape hatch. :)

Starting beta30, you can now do this:

.. contents::
   :local:
   :class: this-will-duplicate-information-and-it-is-still-useful-here

[adamtheturtle]

First of all, thank you @pradyunsg for this great project.

A number of my users have not been able to figure out the right sidebar. I believe that this is because the sidebar does not show in thin windows and the "hamburger" menu item Is not as obvious as a table of contents.

I appreciate the override provided, however, it does make my source somewhat messy.
Also, I would prefer to not change my documentation source, except for conf.py, for a theme.

My preference is that there is no nasty red warning at all around tables of contents.
My preference after that is that disabling those warnings can be a conf.py option.

[pradyunsg]

Appreciate you chiming in, but I disagree that themes should be trivially interchangeable unconditionally, without any consequences. The theme directly contributes to how you'd structure your documentation, and what you're hitting here is a consequence of a design decision and my (fairly steadfast) opinion on not allowing redundant information on the basis of just-because-why-not.

Nearly every Sphinx theme has some quirks or something that doesn't work in it vs others. For this theme, I've basically been very intentional about those and added ridiculously obvious error messages with guidance. Inline TOC on pages is great if you're doing it to provide context (which is what the escape hatch is for). IMO adding one in a 3-column theme is harmful to the readability of the actual content.

A number of my users have not been able to figure out the right sidebar.

Could you start a "Potential Issue" discussion about this at https://github.com/pradyunsg/furo/discussions? I'd like to explore this further.

[adamtheturtle]

Thank you for the considered response. I don't have much experience switching up themes before recently with Furo, so I won't comment on the norm.

I have started #124 and #125 on the topic.

[pradyunsg]

Nope, it doesn't: pradyunsg/sphinx-inline-tabs#9

Now it does! :)

https://pypi.org/project/sphinx-inline-tabs/2021.4.11b8/

[valeriofantozzi]

Alrighty! Color me convinced that folks who know when this is useful should still be able to use local ToCs. However, I'm still very much against allowing folks to be able to do this without much thought on their end.

So, here's my plan: I'll add an escape hatch for this but I don't intend to add any additional CSS to make the ToC look nicer when using this escape hatch. :)

Starting beta30, you can now do this:

.. contents::
   :local:
   :class: this-will-duplicate-information-and-it-is-still-useful-here

Hi,
I'm trying to solve the issue.
How can I disable ToC ?

Thanks :)
Valerio

[pradyunsg]

Please open a new discussion topic.

https://github.com/pradyunsg/furo/discussions/new?category=questions