Journal sphinxcontrib-run: exécuter du code pendant la génération d'une documentation

Je commence l'année par une petite contribution open-source pour les documentations de projets python: sphinxcontrib-run.

TLDR; une directive qui permet d'exécuter du code à la volée pendant la génération d'une doc.

Cette extension au générateur de documentation sphinx concerne la partie des documentations d'API générées automatiquement à partir des commentaires dans le code source, les "docstrings". Les docstrings sont rédigées au format reStructuredText qui est un peu plus évolué que markdown et permet d'appeler des directives avec des arguments pour désigner un bloc de code, une référence, un argument de fonctions, etc.

L'extension sphinxcontrib-run ajoute une nouvelle directive .. run:: qui prend un morceau de code python en argument et l'exécute immédiatement pendant la construction de la documentation. Plus précisément, un interpréteur python est démarré pour chaque page de documentation traitée par sphinx et, à chaque fois que sphinx insère dans la page un nœud correspondant à la directive .. run::, le code est exécuté dans cet interpréteur.

Au passage, ce que le code écrit sur la sortie standard est inséré dans la documentation.

Voici un exemple pour un module python jouet:

"""
.. run::

    from example import square_text_50

    lorem = (
        "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
        + " Pellentesque faucibus vestibulum est id consequat."
        + " Cras sed enim sed ex maximus blandit."
    )
"""


def square_text_50(text):
    """Wrap text to 40 columns.

    .. run::

        print("::")
        print("")
        for line in square_text_50(lorem):
            print("    " + line)
        print("")
    """
    for i in range(0, len(text), 50):
        yield text[i : i + 50]

Si l'on utilise automodule, sphinx va traiter toutes les docstrings à la suite dans la même page, et donc sphinxcontrib-run exécutera les morceaux de code dans le même interpréteur.
La première directive .. run:: fait les imports et instancie une variable globale qui pourra servir plusieurs fois.
La seconde directive intervient dans la documentation de la fonction, elle génère dynamiquement la sortie de la fonction pour faire un exemple.

Dans la documentation, le résultat ressemble à ceci: 

Je vais personnellement utiliser ce projet pour générer automatiquement des figures à insérer dans la doc d'un autre projet, ça m'évitera de les ajouter au dépôt git et d'avoir à les tenir à jour.

Au passage, je note que l'API sphinx pour ajouter des directives est très bien faite et bien documentée.
Enfin, il faut aussi mentionner un projet similaire au mien: https://github.com/sphinx-contrib/eval