Python Language Ecrire de la documentation à l'aide de docstrings


Exemple

Un docstring est un commentaire multi-lignes utilisé pour documenter des modules, des classes, des fonctions et des méthodes. Il doit s'agir de la première déclaration du composant qu'il décrit.

def hello(name):
    """Greet someone.

    Print a greeting ("Hello") for the person with the given name.
    """

    print("Hello "+name)
class Greeter:
    """An object used to greet people.

    It contains multiple greeting functions for several languages
    and times of the  day.
    """

La valeur de docstring est accessible dans le programme et est, par exemple, utilisée par la commande help .

Conventions de syntaxe

PEP 257

PEP 257 définit une norme de syntaxe pour les commentaires docstring. Il permet essentiellement deux types:

  • Docstrings à une ligne:

Selon le PEP 257, ils doivent être utilisés avec des fonctions courtes et simples. Tout est placé sur une ligne, par exemple:

def hello():
    """Say hello to your friends."""
    print("Hello my friends!")

Le docstring doit se terminer par un point, le verbe doit être sous la forme impérative.

  • Docstrings multilignes:

Les docstrings multi-lignes doivent être utilisés pour des fonctions, modules ou classes plus longs et plus complexes.

def hello(name, language="en"):
    """Say hello to a person.

    Arguments:
    name: the name of the person
    language: the language in which the person should be greeted
    """

    print(greeting[language]+" "+name)

Ils commencent par un bref résumé (équivalent au contenu d'une docstring à une ligne) qui peut être sur la même ligne que les guillemets ou sur la ligne suivante, donnant des détails supplémentaires, des paramètres de liste et des valeurs de retour.

Remarque PEP 257 définit quelles informations doivent être données dans un document, il ne définit pas dans quel format il doit être donné. C'était la raison pour laquelle d'autres parties et des outils d'analyse de documentation spécifiaient leurs propres normes pour la documentation, dont certaines sont énumérées ci-dessous et dans cette question .

Sphinx

Sphinx est un outil permettant de générer de la documentation basée sur HTML pour les projets Python basés sur docstrings. Son langage de balisage utilisé est reStructuredText . Ils définissent leurs propres normes pour la documentation, pythonhosted.org en héberge une très bonne description . Le format Sphinx est par exemple utilisé par l' IDE pyCharm .

Une fonction serait documentée comme ceci en utilisant le format Sphinx / reStructuredText:

def hello(name, language="en"):
    """Say hello to a person.

    :param name: the name of the person
    :type name: str
    :param language: the language in which the person should be greeted
    :type language: str
    :return: a number
    :rtype: int
    """

    print(greeting[language]+" "+name)
    return 4

Guide de style Google Python

Google a publié le guide de style Google Python qui définit les conventions de codage pour Python, y compris les commentaires de la documentation. En comparaison avec Sphinx / reST, beaucoup de gens disent que la documentation selon les directives de Google est mieux lisible par l'homme.

La page pythonhosted.org mentionnée ci-dessus fournit également des exemples de documentation conforme au Guide de style de Google.

En utilisant le plug-in Napoleon , Sphinx peut également analyser la documentation dans le format compatible avec Google Style Guide.

Une fonction serait documentée comme ceci en utilisant le format Guide de style de Google:

def hello(name, language="en"):
    """Say hello to a person.

    Args:
        name: the name of the person as string
        language: the language code string

    Returns:
        A number.
    """

    print(greeting[language]+" "+name)
    return 4