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 :
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.