Comment puis-je lier la page d'index générée dans la barre de navigation ReadTheDocs?

Question

Je crée ma documentation avec Sphinx sur ReadTheDocs, en utilisant leur thème. Le processus de construction génère un fichier genindex.html, qui peut être référencée par:

Link to the :ref:`genindex` page. 

qui crée:

Lien vers la page Index.

Je ne peux pas ajouter genindex à mon toctree, par exemple comme ceci:

.. toctree: 

    foo 
    bar 
    genindex 

parce qu'il est un fichier généré automatique, qui n'existe pas au temps de rendu. De plus, Sphinx s'attend à ce que genindex soit un fichier lokal appelé genindex.rst.

Comment puis-je l'ajouter à mon ToC/navigation?

Answer 1

Dans la mesure où personne ne publie une meilleure solution, je vais écrire ma solution de contournement comme une solution de travail.

---

Sphinx crée l'index comme denindex.html dans le répertoire racine de construction. Il ne peut pas être référencé dans une directive toctree car cette directive référence les fichiers ReST. Alors, comment le résoudre?

Nous allons donc créer un fichier genindex.rst et le référencer à partir d'une directive toctree. Cela crée également un genindex.html dans le répertoire racine de la génération. Tous les liens sont créés comme prévu. Le fichier genindex.html doit définir un titre tel que "Index", qui est utilisé comme titre de lien dans la barre de navigation. Après avoir écrit tous les fichiers HTML à partir de fichiers ReST, Sphinx génère son index et remplace genindex.html.

fichiers Source:

fichier source index.rst:

.. toctree:: 
    :caption: Introduction 

    chapter1 
    chapter2 

.. toctree:: 
    :caption: Main Documentation 

    chapter3 
    chapter4 

.. toctree:: 
    :caption: Appendix 

    genindex 

fichiers source genindex.rst:

.. This file is a placeholder and will be replaced 

Index 
##### 

Barre de navigation: Capture d'écran