fr en fr en en fr fr fr fr de fr fr en en en en fr en en fr fr fr fr fr fr fr fr fr fr fr fr fr fr en fr en en fr en fr en en fr fr en en fr en en fr en en fr en en fr en en fr fr fr fr fr fr fr fr fr fr fr fr en fr fr fr fr fr fr fr fr fr fr fr fr fr fr fr fr fr fr fr fr fr fr fr fr fr fr fr fr fr fr fr fr fr en fr
Je pensais alors à mettre en place un Wiki (avec Mediawiki). Mais il faut avoué qu’un Wiki c’est pas très beau (désolé Wikipédia) et du coup, sa me rappel beaucoup trop mes années étudiante…
Un collègue m’a montré un outil qu’il utilise : Sphinx
Sphinx est une solution de documentation libre, elle est d’ailleurs à la base de la documentation de Python.
L’utilisation la plus classique de cet outil est de “coder” ses pages en reStructuredText, de les compiler en HTML et de les mettre à disposition sur un serveur Web. Le format de sortie étant du HTML (statique), vous pouvez aussi tout simplement l’ouvrir depuis votre navigateur avec votre contenu en local.
Dans mon utilisation, je vais créer les pages depuis mon PC et les publier sur mon serveur ou tourne un Apache sur mon LAN.
Mon PC étant sous Windows 10, ce tutoriel montre comment installer et utiliser Sphinx sous Windows.
Pour installer Sphinx, vous avez besoin du gestionnaire PIP (Python). Pour avoir Python sous Windows, le plus simple est d’utiliser le gestionnaire de paquet “Chocolatey”. On va donc voir comment installer tous ça.
Pour l’installer copier-coller la commande suivante dans un invite de commandes en tant qu’administrateur :
Vous pouvez aussi le faire en PowerShell. Pour cela, je vous renvoi sur la documentation du package (en anglais).
Pour installer Python, rien de plus simple avec choco. Toujours dans l’invite de commandes :
On valide donc le lancement du script d’installation
Et ainsi, on installe PIP :
python -m pip install -U pip
Au lancement, le programme Python n’était pas reconnu. J’ai alors fermé et relancer un invite de commandes. Ainsi, la commande était reconnu.
On utilise donc PIP fraichement installé :
pip install -U sphinx
Maintenant que tout est installé, on peut passer à la configuration.
La première configuration s’effectue en lançant l’utilitaire sphinx-quickstart.exe. Ce dernier ce trouve dans le dossier Scripts de votre dossier Python. Le mien ce trouve ici : C:\Python37\Scripts\
Avant de le lancer, vous devez pour mettre dans l’emplacement cible de votre documentation. Pour ce tutoriel, je vais prendre les véhicules comme univers (vous comprendrez par la suite). Je vais donc créer un dossier “DocsVehicule” dans Mes Documents et y positionner mon prompt (plus besoin d’être en console admin).
J’exécute alors l’utilitaire C:\Python37\Scripts\sphinx-quickstart.exe :
Vous trouverez ci-dessous les copies d’écran de mes différant choix de configuration :
Séparation des répertoires des fichiers source et de compilation
Nom du projet, auteur, version et langage
Fin du démarrage rapide
On va maintenant éditer le ficher source\conf.py afin d’y spécifier notre thème voulue. On remplace l’attribut de la variable “html_theme” par “sphinx_rtd_theme” comme dans cet extrait de configuration :
1 2 3 4 5 6
# -- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # html_theme = 'sphinx_rtd_theme'
Pour compiler, on lance le fichier make.bat avec comme argument : html.
La méthode la plus simple et de faire un glisser-déposer du fichier dans un invite de commandes et de rajouté “html”.
Lancement du Makefile en Batch
Compilation de la documentation
On ouvre donc le fichier \build\html\index.html dans notre navigateur :
Page par défaut de notre documentation
Voici donc notre documentation, il ne vous reste plus qu’a éditer le fichier source\index.rst et à relancer la compilation pour avoir votre nouveau rendu.
Dans la partie suivante, je vais vous montrer comment écrire vos premiers contenue.
Voici donc ma ré-écriture du fichier index.rst :
1 2 3 4 5 6 7 8
Documentation de description de Véhicule ! ========================================== .. toctree:: :maxdepth: 2 voitures motos
Je spécifie ici deux éléments : “voitures” et “motos”.
Lors de la compilation, le compilateur va alors chercher les fichiers “voitures.rst” et “motos.rst” pour en retranscrire leurs contenues.
Je vais donc créer ces fichiers avec les contenus respectifs suivants :
1 2 3 4 5 6 7 8 9 10 11
BMW === Modèle ------ E90 Audi ==== Modèle ------ A4 TDI
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
Suzuki ====== GSX-R1000 --------- Infos ~~~~~ - 191 ch - 203 kg Yamaha ====== MT-07 ----- Blabla ~~~~~~ Moteur bi-cylindre
Le rendu en HTML donne ceci :
Vous remarquerez que j’ai fais certaine section en 3 niveaux, or, on n’en voit que 2. Cela est du à l’option “maxdepth” qui a pour valeur 2 dans le fichier index.rst. Cette option spécifie donc que l’affichage se fait seulement sur 2 niveaux. Bien entendu, la navigation dans le menu à gauche permet de visualisé les rangs inférieurs (niveaux supérieurs à 2).
Menu dépliant affichant l’arborescence complète
Si vous pensiez voir “voitures” et “motos” dans le menu vous avez tors ! ces directives ne sont que les noms des pages RST de référence et pas des titres. Pour les avoirs, j’aurais du les crées en titres de niveau 1 et ainsi décaler les autres titres d’un niveau.
Pour faire votre documentation, il vous suffit maintenant de structurer vos éléments en reStructuredText. Pour cela, voici un lien pour un guide de démarrage rapide sur le sujet : http://docutils.sourceforge.net/sandbox/wilk/french/quickstart-fr.html
Voici aussi un autre lien qui m’as permis de comprendre cette solution : https://deusyss.developpez.com/tutoriels/Python/SphinxDoc/
Maintenant que votre documentation est faite, elle ne fonctionne qu’en local sur votre PC. Pour l’exporter et le publier sur un serveur, il vous suffit de copier le contenu du dossier html (dans le dossier build) dans le dossier de publication Web de votre serveur (/var/www/html/ par exemple).