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 Epytext
format 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