How to include the toctree in the sidebar of each page

Question

I'm generating html documentation in Sphinx.

How do I modify the sidebar for each of the html pages in my document so that they include the toctree? By default the toctree only seems to display in the master_doc page, and only in the main area instead of the sidebar.

Is there an easy way to do this? I'll be using readthedocs to host the generated documentation, so I would prefer to avoid the use of any third-party plugins, unless they are also available on readthedocs.

score 67 · Accepted Answer · edited Apr 15 '18 at 09:16

You can customize your html sidebar in conf.py.

The default html sidebar consists of 4 templates:

['localtoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html']

In conf.py you could change localtoc.html to globaltoc.html like this:

html_sidebars = { '**': ['globaltoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html'] }

Since this in the end this will be used in HTML files, this should work on ReadTheDocs.

score 11 · Answer 2 · answered Nov 07 '16 at 18:05

11

Including the 'globaltoc.html' has a drawback in that it doesn't show both the global and local toc for the page you're viewing.

It appears that others were irked about this limitation and resulted in the subsequent development of an extension to support a full toc in the sidebar, checkout: https://pypi.python.org/pypi/sphinxcontrib-fulltoc

answered Nov 07 '16 at 18:05

dbailey

1,417
1
10
16

This works great! But I had to `pip install --upgrade setuptools` first, otherwise it failed to install with a weird error: `AttributeError: '_NamespacePath' object has no attribute 'sort'` – alexanderlukanin13 Dec 23 '17 at 07:52
I currently get this error reported when readthedocs tries to install this. – Chris May 30 '18 at 14:04
@Chris I suspect https://github.com/sphinx-contrib/fulltoc/issues/14 is the cause of this, I'll look into shortly. – dbailey Jun 06 '18 at 12:44

score 4 · Answer 3 · answered Nov 19 '19 at 20:47

Nothing will appear in the "Navigation" section of the default Sphinx sidebar until you add the names of files that you want to scan for section headings to the toctree:: directive in your .rst file.

For example, if you want all the headings of your index.rst file to appear in the Navigation pane, write index (without the extension) in the toctree:: list like so:

My Level 1 Heading
==================

Glorious content.

My Level 2 Heading
------------------

More content


.. toctree::
   :maxdepth: 2
   :caption: Contents:

   index

The crucial bit is adding index right there at the end. If you're like me, you start your projects with the auto-generated template from sphinx-quickstart, which (at time of writing) populates your .rst files with EMPTY toctrees.

score 0 · Answer 4 · answered Jul 03 '23 at 10:46

0

don't forget the :hidden: keyword as shown in that code

.. toctree::
    :maxdepth: 1
    :hidden:

    index
    docs/specification
    docs/ux
    docs/database
    docs/techstack
    docs/api
    docs/specialFunctionalities
    enter code here

answered Jul 03 '23 at 10:46

Mohamed Aymn

1

How to include the toctree in the sidebar of each page

4 Answers4

Linked