Générer votre projet avec Sphinx

Générer votre documentation au format HTML

Le fichier index.rst créé par sphinx-quickstart possède déjà du contenu et il est généré comme page de couverture de votre documentation HTML. Il est écrit en reStructuredText, un puissant langage de balisage.

Modifiez le fichier comme suit :

docs/source/index.rst
Welcome to Lumache's documentation!
===================================

**Lumache** (/lu'make/) is a Python library for cooks and food lovers that
creates recipes mixing random ingredients.  It pulls data from the `Open Food
Facts database <https://world.openfoodfacts.org/>`_ and offers a *simple* and
*intuitive* API.

.. note::

   This project is under active development.

Ceci présente plusieurs fonctionnalités de la syntaxe reStructuredText, y compris :

  • Un titre de section utilisant === pour le soulignement,

  • deux exemples d”Inline markup: **emphase forte** (généralement en caractères gras) et d”*emphase* (généralement en italique).

  • un lien externe en ligne,

  • et une admonition en forme de note (une des directives disponibles).

Maintenant, pour le générer avec son nouveau contenu, vous pouvez utiliser la commande sphinx-build comme précédemment, ou profiter du script de confort de la manière suivante :

(.venv) $ cd docs
(.venv) $ make html

Après avoir exécuté cette commande, vous constaterez que index.html reflète les nouveaux changements !

Générer votre documentation dans d’autres formats

Sphinx supporte divers formats en plus du HTML, y compris PDF, EPUB, et autres. Par exemple, pour générer votre documentation au format EPUB, exécutez la commande suivante depuis le répertoire docs· :

(.venv) $ make epub

Après cela, vous trouverez les fichiers correspondant au e-book dans docs/build/epub/. Vous pouvez alors soit ouvrir Lumache.epub avec un lecteur de e-book compatible avec le format EPUB, tel que Calibre, ou prévisualiser index.html dans un navigateur Web.

Note

Pour afficher la liste complète des formats de sortie disponibles, plus quelques commandes utiles supplémentaires, vous pouvez exécuter make help.

Chaque format de sortie possède des options de configuration spécifiques que vous pouvez ajuster, y compris including EPUB. Entre autres, la valeur par défaut de epub_show_urls est inline, ce qui signifie que les URLs apparaissent juste après le lien correspondant, entre parenthèses. Vous pouvez modifier ce comportement en ajoutant le code suivant à la fin de votre fichier conf.py :

# EPUB options
epub_show_urls = 'footnote'

Avec cette valeur, et après avoir exécuté make epub à nouveau, vous remarquerez que les URLs apparaissent désormais comme des notes de bas de page, évitant ainsi d’encombrer le texte. Joli ! Continuez à lire pour explorer d’autres façons de personnaliser Sphinx.

Note

Générer un PDF en utilisant Sphinx peut se faire en exécutant make latexpdf, pourvu que votre système possède une installation fonctionnelle de LaTeX, tel qu’expliqué dans la documentation de sphinx.builders.latex.LaTeXBuilder. Malgré que cela soit parfaitement faisable, de telles installations sont souvent volumineuses et, en général, LaTeX nécessite une configuration soigneuse dans certains cas, mettant la génération de PDF hors du champ de ce tutoriel.