How can I link the generated index page in ReadTheDocs navigation bar?

Question

I'm creating my documentation with Sphinx on ReadTheDocs, using their theme. The build process generates a genindex.html file, which can be referenced with:

Link to the :ref:`genindex` page.

which creates:

Link to the Index page.

I can't add genindex to my toctree, for example like so:

.. toctree:

   foo
   bar
   genindex

because it's an auto generated file, which does not exist at rendertime. Moreover, Sphinx expects genindex to be a lokal file called genindex.rst.

How can I add it to my ToC / navigation?

Answer 1

As far as no one posts a better solution, I'll write down my workaround as a working solution.

---

Sphinx creates the index as a genindex.html in the build root directory. It can't be referenced in a toctree directive, because this directive references ReST files. So how to solve it?

So let's create a genindex.rst file and reference it from a toctree directive. This also creates a genindex.html in the build root directory. All links are created as expected. The genindex.html file needs to define a headline like "Index", which is used as a link title in the navigation bar.

After writing all HTML files from ReST files, Sphinx generates its index and overwrites genindex.html.

Source files:

Source file index.rst:

.. toctree::
   :caption: Introduction

   chapter1
   chapter2

.. toctree::
   :caption: Main Documentation

   chapter3
   chapter4

.. toctree::
   :caption: Appendix

   genindex

Source files genindex.rst:

.. This file is a placeholder and will be replaced

Index
#####

Navigation Bar Screenshot: