Lors de la génération de documentation à l'aide de Sphinx, j'aimerais pouvoir générer deux versions de ma documentation: une comprenant tout, et une avec seulement un ensemble de pages particulier. Quelle est la meilleure façon d'y parvenir?

Je pourrais écrire un script de construction qui déplace les fichiers pour y parvenir, mais ce serait vraiment bien s'il y avait un moyen de dire à sphinx d'exclure ou d'inclure des documents particuliers lors d'une construction particulière.

22
kdt 29 nov. 2011 à 19:35

3 réponses

Meilleure réponse

Le only et les directives ifconfig peuvent être utilisées d'appliquer des conditions dans les pages.

Il ne semble pas y avoir de moyen simple d'utiliser des conditions pour exclure complètement des pages entières (fichiers .rst).

Ce qui suit (dans index.rst) exclut la référence à doc2.html dans le toctree dans index.html lors de la génération de la sortie HTML:

.. toctree::
   doc1.rst

.. only:: latex

   .. toctree::
      doc2.rst

Mais cela ne fonctionne pas vraiment. Le fichier doc2.html est toujours généré et il est accessible via le lien "Sujet suivant" lorsque doc1.html est le sujet actuel.

8
Alexander Fasching 15 juil. 2019 à 08:59

Qu'en est-il de sphinx.ext.ifconfig? Vous définissez des valeurs de configuration dans votre fichier conf.py. Comme il s'agit d'un fichier Python standard, vous pouvez rendre vos critères d'inclusion intelligents et automatiques si vous en avez besoin.

4
Jon Olav Vik 2 déc. 2011 à 08:21

Ma réponse arrive peut-être un peu tard, mais j'ai réussi à le faire avec Sphinx via exclure des modèles dans le fichier de configuration.

Ma documentation est en partie destinée aux utilisateurs et en partie aux administrateurs.
Certaines pages ont des noms de fichiers qui contiennent le mot admin, et comme vous, je voulais créer deux versions: une avec tout (les documents administratifs) et une avec toutes les pages "administratives" exclues (les documents utilisateur).

Pour exclure toutes les pages "admin" de tous les sous-dossiers, vous devez ajouter cette ligne au fichier de configuration conf.py:

exclude_patterns = ['**/*admin*']

C'était la partie facile.

Mon problème était que je ne savais pas comment exécuter la génération deux fois, une avec et une sans les motifs d'exclusion sans utiliser deux fichiers de configuration différents.

Je n'ai pas trouvé de solution par moi-même, j'ai donc posé une question ici sur SO et obtenu une réponse:

  • Le fichier de configuration est juste un fichier Python et peut contenir du code Python, qui sera exécuté lors de la construction.
  • Vous pouvez passer des paramètres ("tags") via la ligne de commande qui peut être interrogée dans le fichier de configuration.

J'ai donc ce modèle d'exclusion dans mon fichier de configuration:

exclude_patterns = ['**/*admin*']
if tags.has('adminmode'):
    exclude_patterns = []

Maintenant, je peux exécuter la build sans rien passer, ce qui exclura les fichiers "admin":

make clean
make html

⇒ voici ma documentation utilisateur

... et je peux définir la balise "adminmode", qui n'exclura rien:
(syntaxe de ligne de commande Windows)

set SPHINXOPTS=-t adminmode
make clean
make html

⇒ ceci est ma documentation d'administration.


Bonus:

Je peux utiliser la même balise pour ignorer certains contenus spécifiques sur une page, en Inclusion de contenu basé sur des balises.

Exemple:

regular documentation
=====================

This paragraph and its headline will always be visible.

.. only:: adminmode

        secret admin stuff
        ------------------

        This paragraph will be visible in the admin docs only.


This will (again) always be visible.
26
Community 23 mai 2017 à 12:18
8313476