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

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

    enter image description here