Tout savoir sur Sphinx, l’outil de création documentaire pour la data

Sphinx pour la data c’est quoi ?

Vous permettre de construire une documentation agréable à lire et de manière assez facile, telle est la mission de Sphinx.

Il s’agit d’un logiciel en ligne de commande vous permettant de construire automatiquement une documentation (technique, fonctionnelle, etc.). Utilisé pour tout type de projet informatique, il est même utilisé pour documenter le noyau Linux ou encore le projet Jupyter, connu dans le monde de la Data Science.

Comment ça marche ?

Installation

Pour utiliser Sphinx, vous devez disposer de Python.

L’installation peut se faire via le gestionnaire de paquet pip. Les autres méthodes sont décrites dans le guide d’installation de Sphinx (🔗 lien).

Avec pip, l’installation se fait en exécutant la commande suivante :

pip install sphinx

Construire sa doc

Les fichiers sources de votre doc sont au format .rst pour reStructuredText (🔗 lien). Sa syntaxe est relativement simple et est similaire au Markdown, ce qui la rend simple à prendre en main. Ce sont ces fichiers qui seront parsés.

Fonctionnement

De ces fichiers .rst, Sphinx peut générer une documentation au format indiqué lors de l’utilisation de la commande

sphinx-build

Par exemple :

sphinx-build -M html ./source ./build

Va générer la documentation au format html dans le dossier “build”, à partir des fichier .rst du dossier “source”.

💡 Conseil : Vous pouvez initialiser l’architecture de votre projet Sphinx avec la commande :

sphinx-quickstart

Cela va vous mettre en place les dossier et fichiers nécessaires à la rédaction et la construction de votre documentation, plus aisément que si vous deviez le faire manuellement.

Avant de vous montrer comment je me sers de Sphinx dans notre expérimentation DataOps, je vous propose un tour d’horizon d’un fichier dans lequel nous allons montrer à un utilisateur comment cuisiner le meilleur plat sur Terre !

Exemple de page : la bibliothèque pizza !

En guise d’exemple, voici un fichier .rst (merci DuckDuckGo AI Chat) qui montre comment se servir d’une bibliothèque inutile, et donc indispensable : pizza.

Le fichier est composé d’un titre principal et de sections, respectivement soulignés par les caractères = et – .

Les directives code-block (lignes 19 et 26) et toctree (lignes 41) sont utilisées. Une directive est une fonctionnalité de Sphinx comme l’affichage de texte au format de code (code-blocks) et l’affichage d’une table des matières (toctree).

1. code-block nécessite un langage pour pouvoir adapter le format (notamment les couleurs). Ici, il y a du shell et du Python.
2. toctree peut être alimentée de paramètres pour moduler son comportement. Le paramètre maxdepth est calibré à 2 pour faire apparaitre les éléments de la table des matières à l’intérieur des fichiers mentionnés plus bas (installation, utilisation, documentation technique, etc.).

Et c’est tout ce qui compose notre page d’atterrissage, de notre documentation. Facile non ?

Accélérer la livraison de la doc avec Sphinx et GitLab CI !

Vous l’avez compris, Sphinx est un outil puissant qui va à partir de fichiers .rst vous générer des fichiers au format que vous voulez.

En effet, parmi les formats supportés par Sphinx, nous avons la possibilité de faire des pages html, et donc… un site web 😀 !

Dans le cadre de notre expérimentation, nous avons développé une bibliothèque Python. Le code est hébergé sur GitLab, nous permettant de bénéficier de la possibilité de disposer d’un site web sécurisé : les GitLab Pages (🔗 lien).

Pour pouvoir déployer notre site web, les pages doivent être construites au format .html, et stockées dans un endroit particulier dans GitLab. Pour cela, nous avons suivi la documentation de Sphinx concernant la phase de déploiement (🔗 lien). Dans notre contexte, la solution retenue a été de passer par GitLab CI, le service d’intégration et de déploiement continu.

La démarche DataOps apporte une forte automatisation des tâches redondantes, telle que la construction de la documentation. Avec GitLab CI, cette étape se fait automatiquement, et uniquement à chaque nouvelle version de notre bibliothèque !

💡 Pour en savoir plus sur la construction automatique de documentation de code, je vous invite à lire cette page de la doc de Sphinx : 🔗 lien (qui est exactement ce que l’on fait dans cette expérimentation)

L’avis de l’expert sur Spinx pour la Data

Tout d’abord, merci à Quentin Caron, développeur Python de la practice Software Engineering pour cette découverte !

Ensuite, j’adore documenter mes projets avec Sphinx. Le site que je génère est bien fait sans avoir à trop prendre de temps de rédaction, et ça, c’est top (Vive la loi de Pareto) !

En complément de la facilité de création de la documentation, c’est sa possibilité de la générer selon un format souhaité (pdf, epub, html) et sa capacité à se greffer à un projet de code pour générer automatiquement les pages qui m’ont poussée à le choisir pour documenter un de mes projets.

Maintenant, je tiens à placer ici un 🚨 WARNING : j’ai fait le choix de documenter un projet existant, et déjà bien avancé. Certes la construction des pages est quelques chose plutôt facile, mais dans un projet de documentation de code, cela ne constitue que la face émergée de l’iceberg. Dans un tel projet, vous avez une partie dédiée au code source, dans laquelle vous présentez les classes, les méthodes, etc., que vos utilisateurs peuvent exploiter. Et c’est là où le bât blesse, puisque cela nécessite une chose : avoir des docstrings adaptées à Sphinx. Cela est très important pour permettre d’afficher des informations (paramètres à utiliser, leurs types, du texte, des exemples d’utilisation) selon un format spécifique. Dans notre cas, l’intégration de Sphinx a nécessité une réécriture de toutes les docstrings, ce qui prend du temps.

 

Je n’en dirais pas plus sur ce warning, mais un conseil : faite attention à vos docstrings et suivez le modèle de Sphinx (🔗 lien) pour vous assurer de toujours avoir des docstrings adaptées à un outil tel que Sphinx.

Si cet article a piqué votre curiosité, un tuto est disponible 🔗 ici pour construire votre première documentation !

Vous souhaitez avoir plus d’informations ? Contactez-moi via LinkedIn !