2

When generating sphinx documentation using the default settings (including the Alabaster theme), the TOC sidebar only shows the top level headings for the entire document. It used to show the second-plus level headings for the current page. How do I fix this?

(Note: IIRC this used to be affected by whether or not globaltoc.html or localtoc.html was included in html_sidebars, but it seems with Alabaster and/or recent versions, neither of those exist.)

Matthew
  • 2,593
  • 22
  • 25

1 Answers1

0

It turns out this is due to a stupid and easy-to-overlook default when generating a new Sphinx project. Specifically, the default TOC looks like:

.. toctree::
    :maxdepth: 1
    :caption: Contents:

    overview
    topic1
    topic2
    ...

The problem is the maxdepth. It turns out this doesn't just control the number of heading levels that will be displayed in the TOC that appears in the body of the index page, but also the local TOC depth as it appears in the sidebar. Apparently, new projects get a maxdepth of 1, which means that no local TOC's will be seen.

Matthew
  • 2,593
  • 22
  • 25
  • Hmm, on second blush, I may have cargo-culted the `:maxdepth: 1` from somewhere else... Still, wasn't obvious why local TOC's weren't working; hopefully this will help someone else who is similarly stumped! – Matthew May 29 '19 at 20:16