Menu hierarchy broken for local TOCs

[peterthomassen]

Details

• Read the Docs project URL: https://readthedocs.org/projects/desec/
• Build URL (if applicable): https://desec.readthedocs.io/en/latest/

Expected Result

In the menu on the left, submenus should expand correctly. For example, under the item "Retrieving and Manipulating DNS Information", there is an item "Creating an RRset". This section has subsections, and thus the menu item is preceded by a + symbol.

The expectation is that when you click on the + symbol in front of "Creating an RRset", the menu expands and displays the titles of the subsections.

Actual Result

The "Creating an RRset" menu item has a + in front, but click on it does not expand any items. Instead, the subsections already are displayed in the minute from the beginning, on the same hierarchy level as the "Creating an RRset" section itself (although it is the parent section).

Other thoughts

I believe this is a rtd problem, but it also may be a problem with the documentation source. However, in the text itself, the hierarchy itself is displayed correctly, so I'm not sure what to think. Here's the documentation source: https://github.com/desec-io/desec-stack/tree/master/docs/

[stsewd]

Hmm, this works fine on https://docs.readthedocs.io/en/stable/config-file/v2.html

Also, you should try creating a sphinx project (currently rtd is generating some default files for you)
https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html It may be related to that.

And If this is a bug, you should report it to https://github.com/readthedocs/sphinx_rtd_theme

And finally, looks like you are using a single html instead of several pages. Please create a sphinx project and let us know if you replicate that locally with a normal build and single html.

[stsewd]

And If this is a bug, you should report it to https://github.com/readthedocs/sphinx_rtd_theme

I just transferred the issue for you :)

[agjohnson]

The RTD docs have the correct behavior likely because it's using the global toc (we are linking pages with toctree directives). These docs rely on a localtoc, which behaves far differently in Spinx. The local toc tree is what you get when you omit a toctree directive and rely on just the page headings to populate the navigation.

The results here don't look correct though, obviously. However, we haven't had this issue with local toctrees before, so this is either a regression (or it could just be a poorly tested use case), or something like the usage of something like include is causing problems with the toctree (unlikely).

[peterthomassen]

@agjohnson I'm not sure: Does your message imply that there's something we can do in our docs themselves to fix the problem (like adding or removing a directive)?

[peterthomassen]

We switched to a proper Sphinx project with toctree directives, so the problem is no longer relevant for us. Thanks for the advice!

However, I guess it's still a bug, so if you would like to investigate in the future, here's the historic revision of our docs that reproduces the problem: https://github.com/desec-io/desec-stack/tree/4136abc442255b9bbf379dad7f28085b9d0586a8/docs

On the other hand, I don't mind if you close this.

[omarryhan]

Hey, I'm also facing a similar problem here: https://aiogoogle.readthedocs.io/en/latest/.
Under "Authentication", the hierarchy should be as follows:

• (-) User Account
  • OAuth2
  • OpenID Connect
• (-) Service Account
  • OAuth2
• Anonymous Principal (API Keys)

Instead, it's like this

• (+/-) User Account
• OAuth2
• OpenID Connect
• (+/-) Service Account
• OAuth2
• Anonymous Principal (API Keys)

What would be the easiest way to fix it? Thanks.

[stsewd]

@omarryhan your index.rst should have a toctree directive https://github.com/omarryhan/aiogoogle/blob/master/docs/index.rst. This is mentioned by the auto generated comment from sphinx as well

.. Aiogoogle documentation master file, created by
   sphinx-quickstart on Tue Nov 20 20:02:59 2018.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

See https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#toctree-directive

[omarryhan]

Thanks, that fixed it!

I'm getting these two lines of error now:

preparing documents... /home/omar/aiogoogle/docs/index.rst: WARNING: self referenced toctree found. Ignored.
/home/omar/aiogoogle/docs/index.rst: WARNING: circular toctree references detected, ignoring: index <- index

But judging by the fact that it says that this is being ignored and also the fact that the docs are being generated just fine, I'll probably ignore it for now.

[flying-sheep]

I guess the correct way to avoid cycles is

.. toctree::

   self

but I can’t figure out how to get subheadings into the sidebar that way, no config option seems to have an effect.

See sphinx-doc/sphinx#2103