Toc not expanding

[dickreuter]

When I create the sphinx doc the table of contents is not expandable. When I click on the + sign it only overlays a gray colour on all the items below but does not expand anything.

[ghost]

Can you please give us some more information on the build, including a link if possible.

[kadrach]

This sounds exactly like the issue I am currently experiencing:

See how the subsections are not collapsed at all, and clicking the little "+" produces the expected "expanded" result?

Reproducible example:

Sphinx                     1.6.5                     
sphinx-rtd-theme           0.2.5b1

sphinx-quickstart accepting all defaults, and setting theme to sphinx_rtd_theme.

.. index.rst
.. rubric:: Summary
.. rubric:: Foo

Model theory and selection 
========================== 
  
Description 
----------- 
  
Literature review 
----------------- 

Theoretical model 
----------------- 
  
Empirical model estimation technique 
------------------------------------

Model component flow chart
--------------------------

Data preparation
================

[kadrach]

Additionally I also see this issue with sphinx_rtd_theme==0.2.4 and current git master.

And in case that's a CSS/JS issue, I see this in Firefox Nightly, Chrome 58 and Edge.

[dplanella]

If it helps debugging, you can see this issue in action here:

http://adafruit-beaglebone-io-python.readthedocs.io

It seems to be a few separate issues. Navigation items appear twice:

• once collapsed, with the right indentation between levels, and
• once expanded, with no indentation or no indication at all of which navigation level they are

Upon clicking on the '+' sign of the collapsed items, they are expanded, and as the comment and gif animation from @kadrach show, a grey overlay is shown. That adds the correct indentation to the items underneath the expanded level, but still shows the expanded (and redundant) items underneath.

If you happen to test it on the link given, you'll notice that after expanding the "Adafruit Beaglebone I/O Python API" header, the "Pins for SPI0 and SPI1" subheader is again shown twice under the expanded items: once expanded, and once collapsed under the right parent header: "SPI – Serial Peripheral Interface".

For comparison, the Blender docs seem to show the expected behaviour with regards to collapsing/expanding navigation items and their indentation.

The only workaround I've found to make the TOC navigation somehow sane is to use:

html_theme_options = {
    'collapse_navigation': False,
    'sticky_navigation': False,
}

This does not produce the intended results, but at least it shows:

• No (duplicate) collapsed items. The ability to expand any items is also removed. I think that's issue Disabled collapse_navigation stops working when sticky_navigation is also disabled #481, too
• All navigation items apear listed in the TOC, with no indentation to show which level they belong too. Not optimal, but less confusing than having the duplicate entries.

[dplanella]

I've tracked this to be an issue only when you use a single index.rst that contains all your documentation. This works well with Sphinx's built-in themes, but it does confuse sphinx_rtd_theme.

If you change the layout of your documentation to be a master index.rst that includes only a list of separate rst files that contain the actual documentation, then the sidebar TOC entries work as expected.

[jessetan]

This also happens when building singlehtml and is a result of this SASS statement. If I comment it out, the toctree behaves as expected.
However I'm not clear why this local-toc class was needed for singlehtml build. @ericholscher @agjohnson do you know the history behind this?

[ericholscher]

I believe it was in #375

Singlehtml builds were breaking on RTD, but I don't fully remember what the actual issue was.

[ericholscher]

Think it might have been a sphinx bug that has since been fixed perhaps.

[jgehrcke]

If you change the layout of your documentation to be a master index.rst that includes only a list of separate rst files that contain the actual documentation, then the sidebar TOC entries work as expected.

I had the same challenge to overcome, and this is the solution that works. My documentation does not have a lot of content so I initially decided to maintain it in a single file. I switched to distributing it across multiple files "just" for making the sidebar to work as expected. That's OK for me.

[stephenfin]

I think I'm still seeing the same issue here. I don't have a version of sphinx_rtd_theme defined in requirements so it should be using the latest version, right? As with @dplanella, this is a single page build. Other projects using multiple pages work as expected.

[davidfischer]

I don't have a version of sphinx_rtd_theme defined in requirements so it should be using the latest version, right?

Until readthedocs/readthedocs.org#4096 is merged, you are not using the latest theme.

I don't yet know whether this is a Sphinx or theme issue yet though.

[KubaO]

This is not resolved. Single file builds still have a broken toc. Please reopen. This is not a new issue either, it has been around for about 4 years now and it never got fixed. Really.

[LukasVik]

Commenting so that thread will be bumped.

This issue is not resolved (see comment above). Please reopen this issue.

[astrojuanlu]

@LukasVik could you please share more details of where are you seeing this? Project URL, build logs, and so forth?

[LukasVik]

Hello @astrojuanlu

The MWE above, #445 (comment), works now from what I can tell. But adding a sub-heading yields similar behavior as the error encountered there.

Environment:

• Python 3.8.10 in a clean virtualenv
• sphinx 4.3.2 cleanly installed via pip
• sphinx_rtd_theme 1.0.0 cleanly installed via pip

index.rst:

Model theory and selection 
========================== 
  

Description 
----------- 
  

Sub-heading
___________


Theoretical model 
----------------- 
  

conf.py (defaults from sphinx-quickstart except changed theme)

# -- Project information -----------------------------------------------------

project = 'MWE'
copyright = '2022, MWE'
author = 'MWE'

# The full version, including alpha/beta/rc tags
release = 'MWE'


# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
]

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']


# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = 'sphinx_rtd_theme'

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']

Command run:

make html
firefox _build/html/index.html

Result:

After clicking the +:

Here I would not expect to see "Sub-heading", since it is a sub-heading of "Description".

After clicking the + at "Description"

Here I would expect "Description" to remain indented the way it was before. I would also expect "Sub-heading" to appear and be indented one level further than "Description".

[astrojuanlu]

Thanks for the reproducer @LukasVik . Looks like this is worth reopening.

[SeanSnyders]

In the last image in the recent example above (after expanding "Description"), I would also expect "Theoretical model" to stay on the same level as "Description" and not indent with "Sub-heading".

[LukasVik]

@SeanSnyders Yes, agreed!