How to add Sphinx-generated index to the sidebar when using Read the Docs theme?

Question

I'd like to have a link to the automatically generated index in the sidebar when using sphinx-rtd-theme. I've tried adding it to the toctree:

.. toctree::

    first
    second
    Index <:ref:`genindex`>

but this resulted in

WARNING: toctree contains reference to nonexisting document u':ref:`geinindex`'

from Sphinx and no other effect.

I think I could simply hardcode the index in the theme layout.html file, but perhaps there is some better way, not involving modifying the standard theme?

TIA for any hints!

Gringo Suave · Accepted Answer · 2019-03-02T17:31:36.090

25

It's easy if you understand how Sphinx and Jinja work. Unfortunately the Sphinx docs on templating don't give you enough info if you don't. In short, you'll have to override the template:

Make sure you have a _templates folder under your sphinx docs folder.
Make sure it is listed in your conf.py, e.g. templates_path = ['_templates']
Create a file inside the folder called layout.html.
Put this snippet inside and save. The exclamation point/mark forces jinja to use the parent template. Don't forget it, or you'll get a recursion error. You only need to override the menu block.
```
{% extends "!layout.html" %}

  {% block menu %}
    {{ super() }}
    <a href="genindex.html">Index</a>
  {% endblock %}
```

edited Mar 02 '19 at 17:31

answered Jun 15 '16 at 19:08

Gringo Suave

29,931
6
88
75

1

This works, but this doesn't add the index link on the home page toctree, only on the sidebar toctree. – roipoussiere Oct 02 '16 at 19:30
Yes, that's what the question asked for. Combine with Steven's answer if you need it on the same page as the toctree. Often it is there by default. – Gringo Suave Oct 05 '16 at 02:07
Thanks, this is indeed much better than hacking the themes `layout.html` as I ended up by doing back in 2014, I've now switched to this solution (better late than never -- and the same goes for accepting this as the answer :-) – VZ. Dec 29 '16 at 17:09
Works like charm. I did not have the layout.html file (using a ready made template) so added an empty one and then added the code given and all worked well. thanks – user-asterix Mar 06 '19 at 23:37
7

The above solution works only for flat html directory structures (no subdirectories). I recommend to use `Index` instead. Then it also works for nested directory structures – steve Nov 15 '19 at 10:30
While this answer and @steve's note got me on the right page, I found that the formatting of the 'Index' entry on my sidebar looked terrible until I surrounded it with other HTML that matched what I was seeing on the HTML generated for the sidebar for adjacent entries. In my case, that was: ```
Header For Index
- Index
```
– Brad Mar 16 '22 at 19:14

score 3 · Answer 2 · answered Feb 25 '15 at 00:43

3

How about:

.. toctree::

    first
    second

* :ref:`genindex`

answered Feb 25 '15 at 00:43

Steven Almeroth

7,758
2
50
57

This works but add a blank line between the toc and the index link. – roipoussiere Oct 02 '16 at 19:28

score 1 · Answer 3 · answered Mar 31 '22 at 03:49

@Gringo's code got me close. Here is how to match the formatting. @brad also has this in the comments but hard to read wo line spacing. Note, read @Gringo's instructions on where to put this code.

{% extends "!layout.html" %}

{% block menu %}
   {{ super() }}
   <p class="caption">
     <span class="caption-text">Indices</span>
   </p>
   <ul>
        <li class="toctree-l1"><a href= "{{pathto('genindex.html', 1)}}">Everything</a></li>
        <li class="toctree-l1"><a href= "{{pathto('py-modindex.html', 1)}}">Module Index</a></li>
   </ul>
    
{% endblock %}

How to add Sphinx-generated index to the sidebar when using Read the Docs theme?

3 Answers3