Les docstrings sont des chaînes de documentations très utiles pour le partage de code, son évolution, les travaux en groupe et la détection d'erreur entre autres. Découvrons ce dont il s’agit et ses avantages plus en détail.
Définition d’une DocString en Python
Une DocString représente la documentation d’un code. Cela permet aux autres développeurs ainsi qu’à vous-même, lorsque vous revenez sur votre code, de comprendre très facilement le fonctionnement de vos différents bouts de code.
Vous pouvez documenter vos fonctions, vos classes, vos méthodes etc. Cette pratique peut sembler superflue mais peut vous faire gagner énormément de temps à vous et vos lecteurs. Premièrement si vous travaillez en équipe sur le même projet, vous n’êtes pas obligé d’expliquer les éléments de votre code à l’oral, cela vous évite également de vous répéter. De plus, si votre programme doit être modifié plusieurs mois après son déploiement, celui qui s’en chargera n’aura aucun mal à le comprendre.
Le fait de documenter vos composants vous obligera à créer des fonctions simples car vous vous rendrez compte de sa complexité en la documentant. Par ailleurs, lorsqu’une erreur apparaît, il est beaucoup plus facile de retrouver le problème lorsque vos éléments sont clairement documentés.
Comment utiliser les DocStrings sur Python ?
Je vais maintenant vous montrer comment créer des DocStrings pour vos fonctions, classes et méthodes sur Visual Studio Code avec Python.
Tout d’abord installez les extensions suivantes: **Python** et **autoDocString – Python DocString Generator** à votre IDE.
L’extension autoDocString vous permet de créer le corps de votre DocString automatiquement. Il suffit d’écrire votre fonction, vous pouvez spécifier le type de vos paramètres ainsi que le type du retour. Puis, en dessous de la fonction, commencez à taper les 3 guillemets (« » ») et autoDocString vous proposera de remplir la DocString de votre fonction.
Voici le résultat :
L’extension Python vous affiche des renseignements sur la fonction, classe ou méthode que vous êtes en train d’utiliser. Cette extension fonctionne avec n’importe quelle fonction python mais également avec les vôtres. Vous n’avez donc pas besoin de trouver l’élément et de regarder sa documentation dans son fichier, vous avez tout à disposition directement.
Voici un exemple basé sur la capture précédente :
Vous pouvez également vous amuser à utiliser la fonction help() ou l’attribut __doc__ sur vos fonctions afin d’afficher la documentation de celles-ci.
Générer des documentations en HTML automatiquement
Pour finir, je vais vous présenter un outil pour générer des documentations HTML : Sphinx. Je vais vous présenter un petit tutoriel pour créer votre première documentation en HTML sous Ubuntu.
1. Créez un dossier sphinx_project/
2. Dans ce dossier, créez le dossier docs/ ainsi que le dossier my_math/
3. Dans le dossier my_math/ : créez 2 fichiers « my_exp.py » et « my_add.py » dans lesquels, en vous aidant de l’image ci-dessus, vous allez rajouter une fonction « my_add » qui retourne l’addition de 2 nombres. Créez également un fichier « __init__.py » vide.
4. Installez « sphinx » et « sphinx-rtd-theme » à l’aide de pip. Vous pouvez trouver la liste des thèmes proposés par Sphinx à cette adresse https://sphinx-themes.org/.
5. Dans le dossier docs/, lancez la commande « sphinx-quickstart ». Pour la première question, tapez « Entrée », puis renseignez votre nom de projet, votre nom, puis 2 fois « Entrée ». Cette commande crée des dossiers et fichiers sources afin d’utiliser Sphinx.
6. Dans le dossier sphinx_project/, lancez la commande « sphinx-apidoc -o docs . ». Cette commande va créer 2 fichiers « .rst » qui permettront à Sphinx de créer du code HTML suivant les fichiers « .py » trouvés récursivement.
7. Maintenant , nous devons éditer le fichier « docs/index.rst », et ajouter « modules ». Nous informons à Sphinx de construire la documentation suivant le fichier de configuration « modules.rst ».
8. Éditez à présent le fichier « docs/conf.py », qui devra ressembler à ceci :
Dans ce fichier nous avons :
- ajouté le chemin du projet (ligne 9 à 12)
- ajouté des extensions basiques (ligne 21)
- changé le thème (ligne 31)
9. Enfin, dans le dossier docs/, lancez la commande « make html ». Vous trouverez les fichiers html dans ce dossier docs/_build/html. Ouvrez depuis votre manager de fichiers le fichier « index.html » et cliquez ensuite sur « my_math package », vous devriez avoir un résultat similaire à celui-ci :
Conclusion
Vous êtes désormais capable de créer des DocStrings ainsi qu’un fichier HTML correspondant. Votre code sera maintenant plus compréhensible et vos programmes seront facilement scalables. Il s’agit d’une bonne pratique utilisée par les Data Engineers, Data Scientists et les Data Analysts qui travaillent sur d’importants projets. Si vous souhaitez en apprendre plus sur les compétences des ces métiers, je vous invite à consulter nos syllabus sur ces métiers d’avenir sur notre site.
