J'ai vu différents styles d'écriture de docstrings en Python, y a-t-il un style officiel ou "convenu"?

Les formats

Les docstrings Python peuvent être écrits en suivant plusieurs formats comme les autres articles l'ont montré. Cependant, le format de docstring Sphinx par défaut n'a pas été mentionné et est basé sur reStructuredText (reST) . Vous pouvez obtenir des informations sur les principaux formats dans cet article de blog .

Notez que le reST est recommandé par le PEP 287

Voici les principaux formats utilisés pour les docstrings.

- Epytext

Historiquement, un style de javadoc était répandu, il a donc été pris comme base pour Epydoc (avec le Epytextformat appelé ) pour générer de la documentation.

Exemple:

"""
This is a javadoc style.

@param param1: this is a first param
@param param2: this is a second param
@return: this is a description of what is returned
@raise keyError: raises an exception
"""

- du repos

De nos jours, le format probablement le plus répandu est le format reStructuredText (reST) utilisé par Sphinx pour générer de la documentation. Remarque: il est utilisé par défaut dans JetBrains PyCharm (tapez des guillemets triples après avoir défini une méthode et appuyez sur Entrée). Il est également utilisé par défaut comme format de sortie dans Pyment.

Exemple:

"""
This is a reST style.

:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""

- Google

Google a son propre format qui est souvent utilisé. Il peut également être interprété par Sphinx (c'est-à-dire en utilisant le plugin Napoléon ).

Exemple:

"""
This is an example of Google style.

Args:
    param1: This is the first param.
    param2: This is a second param.

Returns:
    This is a description of what is returned.

Raises:
    KeyError: Raises an exception.
"""

Même plus d'exemples

- Numpydoc

Notez que Numpy recommande de suivre leur propre numpydoc basé sur le format Google et utilisable par Sphinx.

"""
My numpydoc description of a kind
of very exhautive numpydoc format docstring.

Parameters
----------
first : array_like
    the 1st param name `first`
second :
    the 2nd param
third : {'value', 'other'}, optional
    the 3rd param, by default 'value'

Returns
-------
string
    a value in a string

Raises
------
KeyError
    when a key error
OtherError
    when an other error
"""

Conversion / génération

Il est possible d'utiliser un outil comme Pyment pour générer automatiquement des docstrings vers un projet Python non encore documenté, ou pour convertir des docstrings existantes (peut mélanger plusieurs formats) d'un format à un autre.

Remarque: Les exemples sont tirés de la documentation Pyment

Le guide de style Google contient un excellent guide de style Python. Il comprend des conventions pour la syntaxe de docstring lisible qui offre un meilleur guidage que PEP-257. Par exemple:

def square_root(n):
    """Calculate the square root of a number.

    Args:
        n: the number to get the square root of.
    Returns:
        the square root of n.
    Raises:
        TypeError: if n is not a number.
        ValueError: if n is negative.

    """
    pass

J'aime étendre cela pour inclure également les informations de type dans les arguments, comme décrit dans ce tutoriel de documentation Sphinx . Par exemple:

def add_value(self, value):
    """Add a new value.

       Args:
           value (str): the value to add.
    """
    pass

Les conventions de docstring sont dans PEP-257 avec beaucoup plus de détails que PEP-8.

Cependant, les docstrings semblent être beaucoup plus personnels que les autres domaines du code. Différents projets auront leur propre standard.

J'ai tendance à toujours inclure des docstrings, car ils ont tendance à montrer comment utiliser la fonction et ce qu'elle fait très rapidement.

Je préfère garder les choses cohérentes, quelle que soit la longueur de la chaîne. J'aime coder l'apparence lorsque l'indentation et l'espacement sont cohérents. Cela signifie que j'utilise:

def sq(n):
    """
    Return the square of n. 
    """
    return n * n

Plus de:

def sq(n):
    """Returns the square of n."""
    return n * n

Et ont tendance à laisser les commentaires sur la première ligne dans des docstrings plus longs:

def sq(n):
    """
    Return the square of n, accepting all numeric types:

    >>> sq(10)
    100

    >>> sq(10.434)
    108.86835599999999

    Raises a TypeError when input is invalid:

    >>> sq(4*'435')
    Traceback (most recent call last):
      ...
    TypeError: can't multiply sequence by non-int of type 'str'

    """
    return n*n

Ce qui signifie que je trouve que les docstrings qui commencent comme ça sont en désordre.

def sq(n):
    """Return the squared result. 
    ...

Comme apparemment personne ne l'a mentionné: vous pouvez également utiliser le Numpy Docstring Standard . Il est largement utilisé dans la communauté scientifique.

• La spécification du format de numpy avec un exemple
• Vous avez une extension sphinx pour le rendre: numpydoc
• Et un exemple de la beauté d'une docstring rendue: http://docs.scipy.org/doc/numpy/reference/generated/numpy.mean.html

L'extension du sphinx napoléon pour analyser les docstrings de style Google (recommandée dans la réponse de @Nathan) prend également en charge la docstring de style Numpy et fait une courte comparaison des deux.

Et dernier exemple de base pour donner une idée à quoi cela ressemble:

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Parameters
    ----------
    arg1 : int
        Description of arg1
    arg2 : str
        Description of arg2

    Returns
    -------
    bool
        Description of return value

    See Also
    --------
    otherfunc : some related other function

    Examples
    --------
    These are written in doctest format, and should illustrate how to
    use the function.

    >>> a=[1,2,3]
    >>> print [x + 3 for x in a]
    [4, 5, 6]
    """
    return True

PEP-8 est la norme de codage python officielle. Il contient une section sur les docstrings, qui fait référence au PEP-257 - une spécification complète pour les docstrings.

C'est Python; tout se passe . Considérez comment publier votre documentation . Les docstrings sont invisibles sauf pour les lecteurs de votre code source.

Les gens aiment vraiment parcourir et rechercher de la documentation sur le Web. Pour ce faire, utilisez l'outil de documentation Sphinx . C'est la norme de facto pour la documentation des projets Python. Le produit est beau - jetez un œil à https://python-guide.readthedocs.org/en/latest/ . Le site Web Read the Docs hébergera vos documents gratuitement.

Je suggère d'utiliser le programme Pep257 Python de Vladimir Keleshev pour vérifier vos docstrings par rapport à PEP-257 et à la norme Numpy Docstring pour décrire les paramètres, les retours, etc.

pep257 signalera la divergence que vous faites par rapport à la norme et est appelé comme pylint et pep8.