Créer automatiquement la documentation Python avec Sphinx

introduction

Bonjour à tous! Êtes-vous en train d'écrire Python? Je crée actuellement un service utilisant Python + django, mais comme vous êtes familier avec Pythonista, vous savez que Python peut avoir une docstring. Par exemple, exécutons un script simple comme celui-ci:

# -*- coding: utf-8 -*-
from __future__ import print_function


def foobar():
    u"C'est une fonction dénuée de sens."
    pass


print(foobar.__doc__)

En Python, vous pouvez attribuer le premier littéral de chaîne qui apparaît dans une fonction, une classe ou une méthode à __doc__ et découvrir plus tard ce que signifie cette fonction. C'est une fonctionnalité intéressante, mais c'est un gaspillage si vous ne pouvez citer que les écrans de la console interactive de Python, les IDE ou divers plugins pour Python.

Donc, si vous utilisez un outil de document appelé Sphinx que Pythonista utilise souvent, cette Docstring sera réunie en une seule. Cette commande est «sphinx-apidoc». Pour plus de détails sur la manière de l'utiliser, veuillez consulter le Document officiel. Espérons qu'un projet Sphinx sera lancé.

Maintenant, en faisant le test, testez avec watchdog ou sniffer Il semble que de nombreuses personnes se connectent et lancent le test chaque fois que le fichier est mis à jour. Par conséquent, j'utilise également le document comme crochet et je le génère automatiquement.

Voici un exemple de sniffer.

@runnable
def execute(*args):
    from subprocess import call
    call('cd ../docs;make html', shell=True)
    return call(
        'python manage.py test users --failfast',
        shell=True) == 0

Pour Linux, sphinx crée un Makefile et construit la documentation à partir de la commande make. En créant des hooks comme celui-ci, vous aurez toujours la dernière documentation à portée de main et vous pourrez vérifier les erreurs de syntaxe reSt involontaires.

Gardez simplement à l'esprit que si vous n'incluez pas le répertoire du document en tant que fichier .gitignore dans Git, cela peut être très ennuyeux.

Bien sûr, certaines personnes peuvent l'utiliser dans un projet dans une autre langue car les performances de génération de documents de Sphinx sont si bonnes, pas dans un projet Python. De plus, certaines personnes peuvent l'utiliser pour fabriquer des matériaux normalement. Dans un tel cas, la combinaison de «sniffer» + «sphinx» est très confortable et est recommandée. Bien sûr, vous pouvez créer d'autres outils de gestion de mise à jour de fichiers.