Comment inclure correctement d'autres fichiers ReST dans un projet sphinx?
Ma documentation manuscrite/guide de l'utilisateur (écrit en ReStructuredText avec sphinx) est devenu assez gros alors j'ai commencé à organiser mes fichiers .rst dans des sous-répertoires.
Dans le index.rst J'inclus un subindex.rst de chaque sous-répertoire qui comprend lui-même d'autres .rst- fichiers pour d'autres sous-répertoires.
index.rst:
.. include:: subdir1/subindex.rst
.. include:: subdir2/subindex.rst
subdir1/subindex.rst:
.. include:: file1.rst
.. include:: file2.rst
En principe, cela fonctionne bien, sauf que sphinx recherche récursivement .rst- fichiers qu'il essaie d'analyser. sans changer le répertoire de travail actuel. Donc, il échoue en voyant include:: file1.rst à l'intérieur subdir1.
Je contourne ce problème en définissant exclude_pattern pour ignorer mes sous-répertoires. Cela ne semble pas correct.
Quelle serait la bonne façon d'inclure un .rst- fichier d'un sous-répertoire?
La directive toctree devrait faire ce que vous voulez.
.. toctree::
:glob:
subdir1/*
subdir2/*
Le glob * triera les fichiers par ordre alphabétique dans subdirs. Pour éviter le tri, vous pouvez spécifier l'ordre sans globbing.
.. toctree::
:maxdepth: 2
subdir1/file2
subdir1/file1
subdir2/file1
subdir2/file2
Si vous ne voulez pas de pages individuelles mais une énorme page, vous pouvez invoquer make singlehtml .