Différences

Ci-dessous, les différences entre deux révisions de la page.

--- dev:python:sphinx:installation [2023/01/02 13:14] – yoann
+++ dev:python:sphinx:installation [2023/10/22 11:24] (Version actuelle) – yoann
@@ Ligne 3: / Ligne 3: @@
 ===== Sphinx : Installation ======
-On active l'environnement virtuel du projet et on installe les modules via pip3
+Sphinx utilise Python et make pour construire la documentation:
+<code bash>
+sudo apt install build-essential python3 python3-pip python3-venv
+</code>
+Créer et activer l'environnement virtuel du projet et on installe les modules via pip3. Ici en plus du module sphinx on installe le thème [[https://docs.readthedocs.io|read the docs]]
 <code bash>
 cd my_app
@@ Ligne 12: / Ligne 18: @@
 Le script **sphinx-quickstart** assiste l'utilisateur pour la création de l'arborescence de base de la documentation et son intégration au sein du projet.
+Se placer à la racine du projet et lancer la commande **sphinx-quickstart**
 <code bash>
 sphinx-quickstart
 </code>
-Ici on fait le choix de créer un répertoire docs à la racine du projet et de produire la documentation technique dans ce répertoire.
+Ici on fait le choix de séparer les répertoires source et build de la documentation.
+Pour plus de clarté, on fait le choix de renommer les répertoires :
+  * ''source'' -> ''doc'' : Pour sphinx ''source'' contient les fichiers sources de la documentation mais dans un projet de code, cela peut porter à confusion.
+  * On crée un sous repertoire dans build pour la documentation.
+Il faudra ensuite modifier le fichier Makefile:
+<code bash>
+mv source doc
+mkdir build/doc
+</code>
+<code bash>
+# Minimal makefile for Sphinx documentation
+#
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = doc
+BUILDDIR      = build/doc
+</code>
+Tester une compilation
+<code bash>
+make html
+</code>
+===== Changer le thème =====
+Le thème "Read The Doc" a été téléchargé mais il n'est pas encore utilisé. Modifier le fichier de configuration ''**doc/conf.py**'' :
+<code python>
+...
+# Utilise le thème Read the Doc
+html_theme = 'sphinx_rtd_theme'
+</code>
+Les nombreuses [[https://sphinx-rtd-theme.readthedocs.io/en/latest/configuring.html|options de configuration du thème]] son décrite dans la documentation officielle du thème.
+<note>
+Pour écrire la documentation dans une autre langue que l'anglais il faut activer l'extension ''sphinx_rtd_theme'' pour permettre la traduction des éléments de l'interface. Modifier le fichier conf.py
+</note>
+<code python>
+...
+extensions = [
+  'sphinx_rtd_theme',
+]
+</code>
 ===== Références =====
   * https://towardsdatascience.com/documenting-python-code-with-sphinx-554e1d6c4f6d?gi=d2b08f5fbc51
   * https://www.sphinx-doc.org/en/master/
+  * https://blog.flozz.fr/2020/09/07/introduction-a-sphinx-un-outil-de-documentation-puissant/

wikinotes

Outils pour utilisateurs

Outils du site

Différences

Outils de la page