Comment documenter du code Python

Si vous débutez en Python et souhaitez aller plus loin, suivez le cours Intermediate Python de DataCamp.

Pourquoi documenter votre projet

La documentation est une composante essentielle de tout projet, quel que soit le langage utilisé. Un projet dont les API fonctionnent et sont utilisées par de nombreux utilisateurs, mais qui n’est pas documenté, sera perçu comme incomplet. Mettez-vous un instant dans la peau d’un développeur : comment vous sentiriez-vous si vous deviez répliquer un projet ou réutiliser une de ses parties sans aucune documentation ? L’intégrer à votre architecture serait probablement un vrai casse-tête.

Une documentation soignée augmente les chances de succès de votre projet. Lorsque vous le partagez avec le monde, vous voulez qu’il soit adopté. C’est d’autant plus vrai pour l’open source, où l’enjeu est majeur. Vous souhaitez aussi que la communauté contribue et l’améliore.

Comme le rappelle le créateur de Python : Code is more often read than written. Cette citation souligne à quel point la documentation est cruciale pour que d’autres puissent comprendre et mettre en œuvre votre code ou votre projet.

Imaginez que vous travaillez chez XYZ, que vous êtes en période de préavis et que votre manager vous demande de transmettre un projet à un collègue. Vous ferez certainement une passation (knowledge transfer), mais que se passe-t-il si votre collègue n’arrive pas à exécuter correctement un script ? Les causes peuvent être multiples : par exemple, des binaires incompatibles avec ceux du système d’exploitation actuel.

Qu’est-ce qu’une documentation, au juste ?

La documentation comporte plusieurs volets. Pour être efficace, elle doit être structurée autour de ces éléments et s’y conformer.

À un niveau macro, on y retrouve :

• Un code source abondamment commenté.

• Le respect des conventions PEP 8 de Python.

• Des tutoriels concrets expliquant comment le projet a été construit, en particulier s’il s’agit d’un projet open source à visée pédagogique.

• Un guide d’installation des paquets et modules nécessaires à la construction du logiciel, ainsi qu’une fiche technique si du matériel est impliqué. Par exemple : installer Anaconda, TensorFlow, Keras, etc.

• Des comptes rendus des décisions et avancées à chaque étape ayant conduit à la mise en production du logiciel.

• Des documents de référence décrivant techniquement la pile technologique utilisée pendant le développement.

• Le design architectural du projet ou de la solution logicielle.

Voici quelques-uns des éléments que l’on retrouve dans une documentation bien conçue. Il est important de les distinguer pour faciliter la maintenance dans le temps.

Un exemple de documentation complète, couvrant la plupart des éléments cités, ressemblerait à ceci :

Beaucoup confondent commenter et documenter et les considèrent comme équivalents. Les commentaires décrivent le code pour l’utilisateur, le mainteneur et pour vous-même à titre de mémo. Les commentaires agissent au niveau du code et constituent un sous-ensemble de la documentation. Ils aident le lecteur à :

• comprendre votre code,
• le rendre le plus autoportant possible, et
• saisir son intention et son design.

N’oubliez pas : Python suit les conventions PEP 8, et les commentaires doivent s’y conformer. La documentation officielle précise que pour les longs blocs de texte peu structurés (docstrings ou commentaires), la longueur des lignes doit être limitée à 72 caractères.

Pour vérifier que votre code respecte PEP 8, vous pouvez utiliser le module Python pylint. Il permet notamment d’ajuster la limite de caractères des commentaires et des autres lignes de code.

Voyons quelques exemples.

• Description d’un module importé

import tensorflow as tf
#imports tensorflow as tf. Tensorflow is an n-dimensional matrix.
#just like a 1-D vector, 2-D array, 3-D array etc.

• Description d’une variable

n_classes = 10 # MNIST total classes (0-9 digits)

Pour aller plus loin sur les bonnes et mauvaises pratiques de commentaire, consultez cet article très utile.

Passons maintenant aux docstrings et à la manière dont elles facilitent la documentation du code de votre projet.

Docstrings pour documenter du code Python

Une docstring Python est une chaîne de documentation (string literal) placée en première instruction dans la définition d’un module, d’une classe, d’une fonction ou d’une méthode. Les docstrings sont accessibles via l’attribut (__doc__) de tout objet Python, et avec la fonction intégrée help(), très pratique.

Les docstrings sont idéales pour décrire la finalité d’un composant : l’objectif général d’une classe, d’un module ou d’une fonction. Les commentaires, eux, portent plutôt sur des lignes, instructions et expressions ponctuelles. Ce sont des textes descriptifs écrits par un programmeur pour se rappeler ce que fait une ligne ou une expression, et pour aider les développeurs qui souhaitent contribuer. Bien documenter votre code est essentiel pour écrire du code propre et des programmes fiables. Il n’existe toutefois pas de règle unique et universelle.

On distingue deux formes de docstrings : sur une ligne et sur plusieurs lignes. Ce sont celles qu’utilisent les data scientists et développeurs dans leurs projets.

• Les docstrings sur une ligne tiennent sur une seule ligne. Utilisez des guillemets triples, simples ou doubles, en veillant à fermer avec le même type. Dans ce format, la fermeture se fait sur la même ligne que l’ouverture. La convention la plus répandue est d’utiliser les triples guillemets doubles.

def square(a):
    '''Returned argument a is squared.'''
    return a**a

print (square.__doc__)


help(square)

Returned argument a is squared.
Help on function square in module __main__:

square(a)
    Returned argument a is squared.

• Les docstrings multilignes utilisent la même syntaxe, suivie d’une ligne vide avant le texte descriptif.

def some_function(argument1):
    """Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value

   """

    return argument1

print(some_function.__doc__)

Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value

À partir du tableau ci-dessus, choisissons Pydoc comme format de docstring et explorons-le.

Vous avez vu que les docstrings sont accessibles via l’attribut Python intégré __doc__ et la fonction help(). Vous pouvez aussi utiliser le module intégré Pydoc, qui offre des fonctionnalités différentes de l’attribut doc et de la fonction help.

Pydoc est un outil très utile lorsque vous souhaitez partager votre code avec des collègues ou en open source, pour toucher un public plus large. Il peut générer des pages web à partir de votre documentation Python et lancer un serveur web.

Voyons comment cela fonctionne.

La façon la plus simple d’exécuter Pydoc est de le lancer comme un script. Dans un notebook Jupyter, on utilise le point d’exclamation (!) pour exécuter la commande.

!python -m pydoc

pydoc - the Python documentation tool

pydoc <name> ...
    Show text documentation on something.  <name> may be the name of a
    Python keyword, topic, function, module, or package, or a dotted
    reference to a class or function within a module or module in a
    package.  If <name> contains a '\', it is used as the path to a
    Python source file to document. If name is 'keywords', 'topics',
    or 'modules', a listing of these things is displayed.

pydoc -k <keyword>
    Search for a keyword in the synopsis lines of all available modules.

pydoc -n <hostname>
    Start an HTTP server with the given hostname (default: localhost).

pydoc -p <port>
    Start an HTTP server on the given port on the local machine.  Port
    number 0 can be used to get an arbitrary unused port.

pydoc -b
    Start an HTTP server on an arbitrary unused port and open a Web browser
    to interactively browse documentation.  This option can be used in
    combination with -n and/or -p.

pydoc -w <name> ...
    Write out the HTML documentation for a module to a file in the current
    directory.  If <name> contains a '\', it is treated as a filename; if
    it names a directory, documentation is written for all the contents.

Comme on le voit ci-dessus, le premier usage de Pydoc est d’afficher la documentation textuelle d’une fonction, d’un module, d’une classe, etc. Voyons en quoi cela peut être plus pratique que help.

!python -m pydoc glob

Help on module glob:

NAME
    glob - Filename globbing utility.

MODULE REFERENCE
    https://docs.python.org/3.7/library/glob

    The following documentation is automatically generated from the Python
    source files.  It may be incomplete, incorrect or include features that
    are considered implementation detail and may vary between Python
    implementations.  When in doubt, consult the module reference at the
    location listed above.

FUNCTIONS
    escape(pathname)
        Escape all special characters.

    glob(pathname, *, recursive=False)
        Return a list of paths matching a pathname pattern.

        The pattern may contain simple shell-style wildcards a la
        fnmatch. However, unlike fnmatch, filenames starting with a
        dot are special cases that are not matched by '*' and '?'
        patterns.

        If recursive is true, the pattern '**' will match any files and
        zero or more directories and subdirectories.

    iglob(pathname, *, recursive=False)
        Return an iterator which yields the paths matching a pathname pattern.

        The pattern may contain simple shell-style wildcards a la
        fnmatch. However, unlike fnmatch, filenames starting with a
        dot are special cases that are not matched by '*' and '?'
        patterns.

        If recursive is true, the pattern '**' will match any files and
        zero or more directories and subdirectories.

DATA
    __all__ = ['glob', 'iglob', 'escape']

FILE
    c:\users\hda3kor\.conda\envs\test\lib\glob.py

Essayons maintenant d’extraire la documentation de glob avec la fonction help.

help(glob)

---------------------------------------------------------------------------

NameError                                 Traceback (most recent call last)

<ipython-input-13-6f504109e3a2> in <module>
----> 1 help(glob)


NameError: name 'glob' is not defined

Comme vous le voyez, une NameError est levée car glob n’est pas défini. Pour utiliser help et obtenir la documentation, il faut d’abord importer le module, ce qui n’est pas nécessaire avec Pydoc.

Explorons maintenant la fonctionnalité la plus intéressante de Pydoc : l’exécuter comme service web.

Pour cela, lancez Pydoc en script avec l’argument -b. Il démarre un serveur HTTP sur un port libre et ouvre un navigateur web pour parcourir la documentation de manière interactive. C’est très pratique si plusieurs services tournent déjà sur votre machine et que vous ne savez plus quel port est disponible.

!python -m pydoc -b

^C

Au lancement de la cellule, une nouvelle fenêtre s’ouvre sur un port aléatoire ; le navigateur ressemble à ceci :

Regardons la documentation du module h5py, un format de fichier utilisé pour stocker les poids d’architectures de réseaux de neurones.

Indispensables pour documenter des projets Python

Quel que soit l’objectif, la vision ou la finalité du projet, la structure de la documentation varie peu. Un projet peut entrer dans les catégories suivantes :

• Projet privé (personnel) : pour constituer un portfolio ou en tant que freelance avec un dépôt GitHub.

• Projet collaboratif (en équipe) : projet mené dans votre organisation ou participation à une compétition Kaggle.

• Projet open source : partagé avec un large public, il attend des contributions, une collaboration active et une bonne maintenabilité du code et de la documentation sur la durée.

Même si la vision diffère selon ces trois catégories, un même canevas de documentation peut s’appliquer partout.

Supposons que vous travailliez sur un projet open source et deviez créer un dépôt GitHub avec une documentation détaillée et tenue à jour ; voici les points essentiels à garder à l’esprit :

• Fichier requirements : souvent oublié, il est pourtant crucial. Il aide les utilisateurs à reproduire votre environnement en un rien de temps. C’est généralement un fichier texte listant tous les paquets et modules, avec leurs versions, utilisés dans le projet. On peut aussi indiquer les dépendances dans le Readme, mais un fichier séparé est préférable : l’utilisateur n’a plus qu’à lancer une commande pip pour installer l’ensemble des dépendances.

• Readme : généralement en Markdown, c’est l’épine dorsale de nombreux projets. Il présente le résumé, les fonctionnalités, la finalité et, idéalement, un joli logo. Il doit inclure des instructions d’installation et d’utilisation. Ajoutez les changements notables depuis la version précédente. Des scripts de test ou un « quick start » pour exécuter le code avec succès renforcent la confiance des utilisateurs. Mentionnez aussi les problèmes potentiels qu’ils pourraient rencontrer.

• Modalités de contribution : indispensable en open source. Décrivez comment les nouveaux contributeurs peuvent participer : développement de fonctionnalités, correction de bugs connus, amélioration de la documentation, ajout de tests, ouverture d’issues… Les contributeurs pourront même publier une v2.0 et faire grandir le projet.

• Licence : un fichier texte clair décrivant la licence (Boost, Apache, MIT, etc.). C’est essentiel en open source. Vous informez l’utilisateur de la liberté d’usage, notamment commercial, et de ses limites.

• Affectation des tâches : pour un projet partagé (ex. Kaggle), précisez qui fait quoi et le niveau d’avancement. Cela facilite le suivi global.

• Réutilisabilité du framework : clé dans un projet d’équipe (ex. Kaggle), afin que vos coéquipiers puissent réutiliser ce que vous avez construit et gagner du temps : pipeline de prétraitement, script de validation croisée, etc.

Pour un excellent exemple de documentation open source, très bien structurée, consultez le dépôt GitHub des transformers huggingface.

Conclusion

Félicitations pour avoir terminé ce tutoriel.

Un bon exercice consiste à explorer davantage le module Pydoc et d’autres formats de docstrings Python comme Epydoc et les docstrings Google, afin de comprendre leurs différences.

N’hésitez pas à poser vos questions sur ce tutoriel dans les commentaires ci-dessous.

Références :

• Docstrings in Python

Si vous débutez en Python et souhaitez aller plus loin, suivez le cours Intermediate Python de DataCamp.