Rendre les niveaux de titre des documents automatiquement dépendants des niveaux de profondeur des (sous (sous (…))) dossiers auxquels ils appartiennent

Dec 04 2020

Supposons que j'ai:

un foo0.rstfichier à la racine ( source) de mon sphinx-docdossier source,
un foo1.rstfichier dans un sous-dossier subfolder1de source,
un foo2.rstfichier dans un sous-dossier subfolder2de subfolder1,

C'est:

$ tree source
source
├── foo0.rst
└── subfolder1
    ├── foo1.rst
    └── subfolder2
        └── foo2.rst

tous avec le même contenu:

This a title
============

Maintenant, si le index.rstcontient:

Welcome to Test's documentation!
================================

.. toctree::
   :maxdepth: 3
   :caption: Contents:

   foo0
   subfolder1/foo1
   subfolder1/subfolder2/foo2

make html donne:

Welcome to Test’s documentation!

Contents:

    • This a title
    • This a title
    • This a title

c'est-à-dire que tous les titres sont des sections.

Ce que je voudrais plutôt obtenir est le suivant:

Welcome to Test’s documentation!

Contents:

    • This a title
      ◦ This a title
        ▪ This a title

c'est l'en-tête de:

foo0.rst être une section,
subfolder1/foo1.rst étant une sous-section (et non une section),
subfolder1/subfolder2/foo2.rst étant une sous-section (et non une section).

Ma question est donc: est-il possible de faire dépendre automatiquement les niveaux d'en-tête des documents appartenant aux (sous (sous (...))) dossiers des niveaux de profondeur des dossiers auxquels ils appartiennent?

Réponses

1 bad_coder Dec 04 2020 at 20:37

Le style appliqué aux toctree entrées dépend du thème que vous utilisez. Le CSS du thème appliquera un style aux entrées dans lesquelles Sphinx a été traduit <ul>et en <li>fonction à la fois de leur place dans la «hiérarchie des documents», compte tenu de la façon dont vous enchaînez toctreeset de l'organisation de votre structure de section dans les .rstfichiers individuels .

Par exemple, inspectez les éléments HTML générés par Sphinx. Le toctreesera un div class="toctree-wrapper compound"avec chaque niveau de sections étant nommé <li class="toctree-l1">alors <li class="toctree-l2">, etc ...

Une façon d'obtenir ce que vous voulez serait d'entourer une donnée en toctreeutilisant une .. class::directive (comme montré ici ) et d'appliquer un style personnalisé . Mais cela aurait alors un impact sur le style de tous les autres .rstfichiers que vous souhaitez inclure en tant qu'entrées toctree.

Dans tous les cas, vous encourrez un travail supplémentaire et un automatisme potentiellement lâche si vous refactorisez votre projet.

Il existe également une solution de contournement possible , en utilisant l' :hidden:option avec la :include:directive. Si vous déclarez un masqué toctreeavant un visible, toctreela "hiérarchie de documents" peut fixer pour vous la position d'une entrée dans la hiérarchie. Ensuite, le visible toctreesans l' :hidden:option rendra .rstles entrées de fichier comme un <li>élément ayant une position fixe dans la hiérarchie. (Un exemple complet peut être vu dans cet article ).

Cela peut être fait, mais vous travaillerez contre les caractéristiques du toctree.

La solution la plus courante consiste à écrire vos .rstfichiers et vos sections en fonction de la manière dont vous souhaitez toctreeafficher le. (Cette approche a tous les avantages avec le seul inconvénient de mettre des restrictions sur la façon dont vous écrivez les .rstfichiers). C'est probablement la solution préférable plutôt que d'essayer d'adapter les styles CSS ou d'utiliser des solutions de contournement.

ÉDITER:

Ce que j'ai écrit avant est valide, mais probablement trop général. Je vais donc donner une solution possible à l'exemple. Si vous souhaitez ce qui suit:

Contents:

    • This a title (foo0)
      ◦ This a title (foo1)
        ▪ This a title (foo2)

Une option simple consiste à utiliser une chaîne de toctrees. Vous pouvez masquer les éléments toctreesitués plus bas dans la hiérarchie du document si vous ne souhaitez pas les voir.