How can i include the `genindex` in a Sphinx TOC?

Question

Sphinx generates an index named genindex when building a documentation and therefore forbids to use that name for a document. Now, how would I include a link to that index in a table of contents?

I've tried this:

.. toctree::
   :maxdepth: 2

   genindex
   api


Indices and tables
==================

* :ref:`genindex`

While the last line does create a link to that index in the document, the build doesn't know the reference when creating the TOC:

WARNING: toctree contains reference to nonexisting document 'genindex'

Does this answer your question? [How can I link the generated index page in ReadTheDocs navigation bar?](https://stackoverflow.com/questions/40556423/how-can-i-link-the-generated-index-page-in-readthedocs-navigation-bar) — Paebbels, Aug 09 '20 at 19:05
Can you please explain the equation: ``4 years, 2 months > 4 years, 9 months`` @Paebbles? — Akib Azmain Turja, Jan 10 '21 at 11:59

score 8 · Accepted Answer · answered Feb 18 '17 at 03:39

8

Create a File genindex.rst with the following Content:

Index
=====

In your index.rst add:

.. toctree::
   :hidden:

   genindex

If you you also want to have the Link and Text "Index" on the Site and not only in the left Navigation then remove :hidden:

answered Feb 18 '17 at 03:39

Dirk Schiller

491
6
18

11

that's funny, the [docs](http://www.sphinx-doc.org/en/stable/markup/toctree.html#special-names) explicitly state not to create a file with that name. – funky-future Feb 27 '17 at 23:06
3

You are right. That can cause Issues. I have one Project where the PDF Creation with rst2pdf doesn't work unless I do not remove the "genindex.rst"-Hack. – Dirk Schiller Mar 01 '17 at 09:14
12

that's not so funny. – funky-future May 03 '19 at 21:11

score 2 · Answer 2 · answered Apr 09 '23 at 20:22

2

Good news, everyone! A patch has been merged and was released with Sphinx 5.2.0. Now genindex, modindex and search can be included as TOC items without further ado.

answered Apr 09 '23 at 20:22

funky-future

3,716
1
30
43

How can i include the `genindex` in a Sphinx TOC?

2 Answers2

Linked