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-02 17:31:36Z

27

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 2, 2019 at 17:31

answered Jun 15, 2016 at 19:08

Gringo Suave

32.3k7 gold badges95 silver badges82 bronze badges

Sign up to request clarification or add additional context in comments.

6 Comments

roipoussiere Over a year ago

This works, but this doesn't add the index link on the home page toctree, only on the sidebar toctree.

Gringo Suave Over a year ago

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.

VZ. Over a year ago

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 :-)

user-asterix Over a year ago

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

steve Over a year ago

The above solution works only for flat html directory structures (no subdirectories). I recommend to use <a href= "{{pathto('genindex.html', 1)}}">Index</a> instead. Then it also works for nested directory structures

|

Steven Almeroth · Accepted Answer · 2015-02-25 00:43:25Z

4

How about:

.. toctree::

    first
    second

* :ref:`genindex`

answered Feb 25, 2015 at 0:43

Steven Almeroth

8,2522 gold badges54 silver badges60 bronze badges

1 Comment

roipoussiere Over a year ago

This works but add a blank line between the toc and the index link.

Eli Holmes · Accepted Answer · 2022-03-31 03:49:20Z

1

@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 %}

answered Mar 31, 2022 at 3:49

Eli Holmes

7067 silver badges12 bronze badges

Collectives™ on Stack Overflow

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

3 Answers 3

6 Comments

1 Comment

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

3 Answers 3

6 Comments

1 Comment

Comments

Your Answer

Sign up or log in

Post as a guest

Related