Tutoriel de mise en place du générateur de documentation Sphinx.

Je cherchais une solution pour écrire de la documentation (notes, procédure…).
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.
Ce système est aussi utilisé par Read the Docs avec un thème propre a eux. Ce thème est, je trouve, pas mal du tout. Comme il le dise, ce thème est moderne et mobile-friendly. Si je vous en parle, c’est parce que ce thème est disponible librement et que l’on peut donc l’utiliser pour faire sa propre documentation. Voyez donc pas vous-même à quoi ressemble ce thème : https://docs.readthedocs.io/en/stable/

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.

Pré-requis

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.

Installation de Chocolatey

Pour l’installer copier-coller la commande suivante dans un invite de commandes en tant qu’administrateur :

@"%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe" -NoProfile -InputFormat None -ExecutionPolicy Bypass -Command "iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))" && SET "PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin"

Vous pouvez aussi le faire en PowerShell. Pour cela, je vous renvoi sur la documentation du package (en anglais).

Python

Pour installer Python, rien de plus simple avec choco. Toujours dans l’invite de commandes :

choco install python

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.

Installation

Sphinx

On utilise donc PIP fraichement installé :

pip install -U sphinx

Thème ReadTheDocs

pip install sphinx_rtd_theme

Maintenant que tout est installé, on peut passer à la configuration.

Configuration

QuickStart

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 :

Changement du thème

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 :

  # -- 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'

Première compilation

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

On ouvre donc le fichier \build\html\index.html dans notre navigateur :

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.

Création de contenu

Voici donc ma ré-écriture du fichier index.rst :

  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 :

BMW
===
Modèle
------
E90

Audi
====
Modèle
------
A4 TDI

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

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/

Publication du site

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