7

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?

bad_coder
  • 11,289
  • 20
  • 44
  • 72
Paebbels
  • 15,573
  • 13
  • 70
  • 139
  • 3
    Workaround: Create a `genindex.rst` file with the headline "Index" and reference it in toctree of `index.rst` (top-level). The created `genindex.html` will be replaced by the generated index, so at the end the link points to the right file. – Paebbels Nov 11 '16 at 21:54
  • Does this answer your question? [How can i include the \`genindex\` in a Sphinx TOC?](https://stackoverflow.com/questions/36235578/how-can-i-include-the-genindex-in-a-sphinx-toc) – Akib Azmain Turja Jan 10 '21 at 09:35
  • @AkibAzmain please see dates of answers and you find mine existed before :) – Paebbels Jan 10 '21 at 10:48
  • Can you please explain the equation: ``4 years, 2 months > 4 years, 9 months`` @Paebbles? – Akib Azmain Turja Jan 10 '21 at 11:57
  • @AkibAzmain this questions was answered 13.11.2016, the answer you linked is 18.02.2017. It's not about when a question was raised, it's about when a questions got answered. Your comment asked: `Does this answer your question?`. If you asked: Has someone asked that before, then yes, it was asked before and I didn't see that 4 years ago. – Paebbels Jan 10 '21 at 16:35

1 Answers1

9

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 denindex.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:

enter image description here

Paebbels
  • 15,573
  • 13
  • 70
  • 139