La directive toctree insère un «arbre de la table des matières» à l'emplacement actuel, en utilisant les tables de matières individuelles (y compris les «arbres de la sous-table des matières») des documents indiqués dans le corps de la directive.

Important: toctree est une directive reStructuredText, on ne peut donc l'utiliser que dans un document reStructuredText.

Les directives peuvent avoir des arguments, des options et du contenu.

Les arguments sont donnés directement après le double deux-points après le nom de la directive. Chaque directive décide si elle peut avoir des arguments et combien.

Les options sont données après les arguments, sous la forme d'une “liste de champs”. maxdepth est une telle option pour la directive toctree .

Le contenu suit les options ou les arguments après une ligne vide. Chaque directive décide d'autoriser ou non le contenu et de quoi faire avec.

Un principe commun aux directives est que la première ligne du contenu doit être indentée au même niveau que les options .

• Les noms de document relatifs (ne commençant pas par une barre oblique) sont relatifs au document dans lequel la directive apparaît, les noms absolus sont relatifs au répertoire source. Une option numérique maxdepth peut être donnée pour indiquer la profondeur de l'arbre; Par défaut, tous les niveaux sont inclus.
• Tous les documents du répertoire source (ou des sous-répertoires) doivent être référencés dans une directive toctree ; Sphinx émettra un avertissement s’il trouve un fichier qui n’est pas inclus dans une toctree , car cela signifie que ce fichier ne sera pas accessible via la navigation standard.
• Utiliser exclude_patterns pour exclure explicitement la création complète de documents ou de répertoires. Utiliser les métadonnées «orphelines» pour créer un document, mais informer Sphinx qu'il n'est pas accessible via un objet clé.
• Le “document maître” (désigné par master_doc dans le fichier conf.py) est la “racine” de la hiérarchie de la table des matières. Il peut être utilisé comme page principale de la documentation ou comme “table des matières complète” si on ne spécifie pas l'option maxdepth.

 .. toctree ::
   :maxdepth: 2

   intro
   strings
   datatypes
   numeric
   (many more documents listed here)

Cela accomplit deux choses:

• Les tables des matières de tous ces documents sont insérées, avec une profondeur maximale de deux, ce qui correspond à un en-tête imbriqué. toctree directives toctree dans ces documents sont également prises en compte.
• Sphinx connaît l'ordre relatif des intro , des strings , etc. des documents, et sait qu'ils sont les enfants du document affiché, l'index des bibliothèques. À partir de ces informations, il génère des liens «chapitre suivant», «chapitre précédent» et «chapitre parent».

Les titres de document dans toctree seront automatiquement lus à partir du titre du document référencé. Mais on peut spécifier un titre explicite et une cible en utilisant une syntaxe similaire à celle des hyperliens reST (et de la syntaxe de référencement croisé de Sphinx). Cela ressemble à:

 .. toctree ::

   intro
   All about strings <strings>
   datatypes

La deuxième ligne ci-dessus renverra au document de strings , mais utilisera le titre «Tout sur les chaînes» au lieu du titre du document de strings .

On peut également ajouter des liens externes en donnant une URL HTTP au lieu d'un nom de document.

Si on veut avoir des numéros de section même en sortie HTML, donner à toplevel une option numbered . Par exemple:

 .. toctree ::
   :numbered:

   foo
   bar

La numérotation commence alors par l'en-tête de foo . Les sous-arbres sont automatiquement numérotés (ne leur donnez pas le drapeau numbered ).

La numérotation jusqu'à une profondeur spécifique est également possible, en donnant la profondeur sous forme d'argument numérique à numbered .

On peut utiliser l'option de caption pour fournir une légende toctree et l'option name pour fournir un nom de cible implicite pouvant être référencé à l'aide de ref :

 .. toctree ::
   :caption: Table of Contents
   :name: mastertoc

   foo

Si on ne veut que seuls les titres des documents de l'arborescence titlesonly, et non d'autres en-têtes de même niveau, utiliser l'option titlesonly :

 .. toctree ::
   :titlesonly:

   foo
   bar

L'option glob dans les directives toctree, toutes les entrées sont ensuite comparées à la liste des documents disponibles et les correspondances sont insérées dans la liste par ordre alphabétique. Exemple:

 .. toctree ::
   :glob:

   intro*
   recipe/*
   *

* Cela inclut d’abord tous les documents dont le nom commence par intro , puis tous les documents du dossier de recipe , puis tous les documents restants (à l’exception de celui contenant la directive, bien sûr.) 2

L'option reversed permet d'inverser l'ordre des entrées de la liste. Cela peut être utile lorsque on utilise l'option glob pour inverser l'ordre des fichiers. Exemple:

 .. toctree ::
   :glob:
   :reversed:

   recipe/*

Lorsqu'on veut gérer ces liens soit-même, dans un style différent ou dans la barre latérale HTML cette option , informera toujours Sphinx de la hiérarchie du document, mais n'insérera pas de liens dans le document à l'emplacement de la directive.

 .. toctree ::
   :hidden:

   doc_1
   doc_2

Lorsqu'on souhaite n’avoir qu’un seul élément de premier niveau et masquer tous les autres éléments de niveau inférieur, ajouter l’option «includehidden» à l’entrée de premier niveau toctree:

 .. toctree ::
   :includehidden:

   doc_1
   doc_2

Toutes les autres entrées toctree peuvent ensuite être éliminées par l’option «hidden».