indexingpython-sphinxrestructuredtextread-the-docstoctree

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


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?


Solution

  • The previously accepted answer by @Paebbels is now outdated and suboptimal since Sphinx enabled the toctree directive to recognise genindex, modindex, and search directly, available starting with Sphinx 5.2.0 (listed as #10673).

    Especially considering Sphinx explicitly advises against creating files with those special names.

    Without creating the name-conflicting files, write the toctree as such:

    .. toctree
       :caption: Appendix
    
       genindex
    

    Credit goes to @funky-future self-answering on 2023-04-09 on the linked issue from the question comments above. I found this question before that one and almost ended up using the approach here, so I felt I should preserve this new approach here as well for posterity.