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