web-dev-qa-db-fra.com

Comment inclure le toctree dans la barre latérale de chaque page

Je génère de la documentation html dans Sphinx.

Comment modifier la barre latérale pour chacune des pages html de mon document afin qu'elles incluent le toctree? Par défaut, le toctree ne semble s'afficher que dans le master_doc page, et uniquement dans la zone principale au lieu de la barre latérale.

Y a-t-il un moyen facile de faire ceci? Je vais utiliser readthedocs pour héberger la documentation générée, donc je préférerais éviter l'utilisation de plugins tiers, à moins qu'ils ne soient également disponibles sur readthedocs.

python-sphinx
39
Travis Bear

Vous pouvez personnaliser votre barre latérale html dans conf.py.

La barre latérale html par défaut se compose de 4 modèles:

['localtoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html']

Dans conf.py vous pouvez remplacer localtoc.html par globaltoc.html comme ceci:

html_sidebars = { '**': ['globaltoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html'] }

Comme cela sera finalement utilisé dans les fichiers HTML, cela devrait fonctionner sur ReadTheDocs.

52
shry

L'inclusion de "globaltoc.html" présente un inconvénient en ce qu'il n'affiche pas à la fois le toc global et local pour la page que vous consultez.

Il semble que d'autres ont été contrariés par cette limitation et ont entraîné le développement ultérieur d'une extension pour prendre en charge un toc complet dans la barre latérale, consultez: https://pypi.python.org/pypi/sphinxcontrib-fulltoc

6
dbailey

Rien n'apparaîtra dans la section "Navigation" de la barre latérale Sphinx par défaut jusqu'à ce que vous ajoutez les noms des fichiers que vous souhaitez analyser pour les en-têtes de section à la toctree:: directive dans votre .rst fichier.

Par exemple, si vous souhaitez que toutes les rubriques de votre index.rst fichier à afficher dans le volet de navigation, écrivez index (sans l'extension) dans le toctree:: liste comme ceci:

My Level 1 Heading
==================

Glorious content.

My Level 2 Heading
------------------

More content


.. toctree::
   :maxdepth: 2
   :caption: Contents:

   index

Le bit crucial est d'ajouter index juste là à la fin. Si vous êtes comme moi, vous démarrez vos projets avec le modèle généré automatiquement à partir de sphinx-quickstart, qui (au moment de la rédaction) remplit votre .rst fichiers avec toctrees VIDE.

1
SigmaX