Sphinx toctree either displays a TOC in sidebar with bulleted list in body, or nothing at all

Question

I'm working with Sphinx (sphinx-1.2b1-py2.7). I want a TOC to appear in a sidebar. It seems binary: I can only get both a TOC in the sidebar and a bulleted list in the body of the text, or I get nothing (no TOC in the sidebar and no bulleted list).

When I use the toctree directive like this:

.. toctree::  
   :hidden:

   Topic1  
   Topic2  

Result: no TOC in the sidebar, no bulleted list of topics in body.

When I use the toctree directive like this:

.. toctree::  

   Topic1  
   Topic2  

Result: TOC in the sidebar AND a bulleted list of topics in the body.

I just want the TOC in the sidebar. Other commands (maxdepth, includehidden) don't work. I've seen it done, but cannot get it to work. The conf.py looks fine, but no luck after several days of searching for an answer. Thanks.

Answer 1

I had trouble with this too; I found the answer here.

The TOC is shown via a call to toctree() inside, e.g., a file called layout.html. In particular, it is shown in the sidebar via a snippet of code similar to the following, which resides in <div class="sidebar">:

{% block sidebartoc %}
<h3>{{ _('Table Of Contents') }}</h3>
{{ toctree() }}
{% endblock %}

Since I am using a theme, layout.html is within the theme directory inside the directory _themes; otherwise layout.html might be inside the directory _templates.

In newer versions of Sphinx, what is needed to display the TOC when :hidden: is used as in

.. toctree::  
   :hidden:

is to add the argument includehidden=True to the call to toctree(), as in

{% block sidebartoc %}
<h3>{{ _('Table Of Contents') }}</h3>
{{ toctree(includehidden=True) }}
{% endblock %}