La documentation d'un projet

Il y a deux niveaux de documentation :

• le manuel : la documentation libre qui accompagne le projet
• l'API ou la référence générée à partir des commentaires du code en particulier les blocs de texte qui décrivent les fonctions et classe (appelés docstring).

Mise en forme

Pour améliorer la lisibilité on peut enrichir la mise en page à l'aide de balises assez discrètes pour que le code reste lisible. Le monde Python propose deux langages pour cela :

• reStructuredText, l'original (extension rst)
• Markdown, plus simple et utilisé ici-même, dans cette cellule de Jupyter (extension md)

Pour la documentation d'une fonction, il faut aussi choix le style qu'on désire pour décrire les arguments, la valeur de retour et d'autres points moins visibles. Voici les trois styles les plus courants :

• reStructuredText pour docstring
• Google style, voir aussi cet exemple
• Numpy style, voir aussi cet exemple

API

La fonction suivante utilise le style Google et le commentaire est écrit en rst (écrire un commentaire en md pose des problèmes d'interprétation pour l'instant).

# %load package/factorial.py

def factorial(n) -> int:
    """
    Return n! 
    
    Factorial(n) or n! = n * (n-1) * (n-2) * ... * 1 and
    0! = 1  (since n! = (n+1)! / (n+1))
     
    Args:
      n (int): a positive integer

    Returns:
      int
        
    Raises:
      TypeError: if n is not an int
      ValueError: if n < 0
      
    Here are some tests. Note that tests also show how to use the function.
        >>> [factorial(n) for n in range(6)]
        [1, 1, 2, 6, 24, 120]
        >>> factorial(-2)
        Traceback (most recent call last):
        ...
        ValueError: n should be positive
        >>> factorial(3.1)                 # doctest: +ELLIPSIS
        Traceback (most recent call last):
        ...
        TypeError:...
    """
    if type(n) != int:
        raise TypeError('Not an integer')
    if n < 0:
        raise ValueError('n should be positive')
    res = 1
    for i in range(2,n+1):
        res *= i
    return res
    

À partir de ce commentaire on peut appeler l'aide en ligne ou générer une documentation.

# aide en ligne. help(factorial) donne le même résultat
factorial?

Voici un exemple de docstring avec le style Numpy :

import numpy as np
np.zeros?

La génération de la documentation nécessite l'utilisation d'un logiciel pour obtenir du HTML ou un autre format. Sphinx est largement utilisé pour cela et voici le résultat :

Sphinx pour l'API

Il n'entre pas dans le cadre de ce cours d'expliquer l'utilisation de Sphinx. On va simplement donner ici les commandes qui permettent de générer un site web avec l'API de son projet.

Installation à main :

• Installer les paquets sphinx et sphinx-autoapi
• Dans le répertoire principal du projet créer un répertoire docs.
• Aller dans ce répertoire, cd docs, puis initier Sphinx : sphinx-quickstart (accepter les réponses par défaut)
• Editer index.rst pour avoir la table des matières ainsi (attention à l'alignement vertical, 'a' en dessous de ':') :

.. toctree::
    :maxdepth: 2
    :caption: Contents:

    autoapi/index.rst

• Editer conf.py
  • pour insérer les extensions nécessaires

    extensions = ['sphinx.ext.doctest', 'autoapi.extension']
    

  • pour ajouter à la fin le générateur de la doc de référence (API)

    autoapi_type = 'python'
    autoapi_dirs = ['../src']
    

• Créer les pages web avec make html et ouvrir avec votre navigateur _build/html/index.html.

Sphinx + Nox

Pour automatiser la mise à jour du site web avec Nox (donc après avoir fait à la main l'installation), on peut ajouter ces lignes à notre fichier noxfile.py :

@nox.session(python="3.8")
def docs(session):
    """Build the documentation."""
    session.run("make", "-C", "docs/", "html")

Et la mise à jour se fait avec nox -s docs.

{{ PreviousNext("91 Tests.ipynb", "../lesson3 Object Python/01 Classes and objects.ipynb") }}