Documentation
Créer des paquetages Python
James Fulton
Climate informatics researcher
Pourquoi inclure de la documentation ?
- Aide vos utilisateurs à utiliser votre code
- Documenter chaque
- Fonction
- Classe
- Méthode de classe
import numpy as np
help(np.sum)
...
sum(a, axis=None, dtype=None, out=None)
Sum of array elements over a given axis.
Parameters
----------
a : array_like
Elements to sum.
axis : None or int or tuple of ints, optional
Axis or axes along which a sum is performed.
The default, axis=None, will sum all of the
elements of the input array.
...
Pourquoi inclure de la documentation ?
- Aide vos utilisateurs à utiliser votre code
- Documenter chaque
- Fonction
- Classe
- Méthode de classe
import numpy as np
help(np.array)
...
array(object, dtype=None, copy=True)
Create an array.
Parameters
----------
object : array_like
An array, any object exposing the array
interface ...
dtype : data-type, optional
The desired data-type for the array.
copy : bool, optional
If true (default), then the object is copied.
...
Pourquoi inclure de la documentation ?
- Aide vos utilisateurs à utiliser votre code
- Documenter chaque
- Fonction
- Classe
- Méthode de classe
import numpy as np
x = np.array([1,2,3,4])
help(x.mean)
...
mean(...) method of numpy.ndarray instance
a.mean(axis=None, dtype=None, out=None)
Returns the average of the array elements
along given axis.
Refer to `numpy.mean` for full documentation.
...
Documentation de fonction
def count_words(filepath, words_list):""" ... """
Documentation de fonction
def count_words(filepath, words_list):"""Compter le nombre total d'occurrences de ces mots."""
Documentation de fonction
def count_words(filepath, words_list):"""Compter le nombre total d'occurrences de ces mots. Le calcul est effectué sur un fichier texte à l'emplacement indiqué. """
Documentation de fonction
def count_words(filepath, words_list):"""Compter le nombre total d'occurrences de ces mots. Le calcul est effectué sur un fichier texte à l'emplacement indiqué. [expliquer ce que sont filepath et words_list] [ce qui est retourné] """
Style de documentation
Style de documentation Google
"""Ligne sommaire.
Description détaillée de la fonction.
Args:
arg1 (int): Description de arg1
arg2 (str): Description de arg2
Style NumPy
"""Ligne sommaire.
Description détaillée de la fonction.
Parameters
----------
arg1 : int
Description de arg1 ...
Returns
----------
numpy.ndarray
Style reStructuredText
"""Ligne sommaire.
Description détaillée de la fonction.
:param arg1: Description de arg1
:type arg1: int
:param arg2: Description de arg2
:type arg2: str
Style Epytext
"""Ligne sommaire.
Description détaillée de la fonction.
@type arg1: int
@param arg1: Description de arg1
@type arg2: str
@param arg2: Description de arg2
Style de documentation NumPy
Populaire dans les bibliothèques scientifiques Python comme
numpyscipypandassklearnmatplotlibdask- etc.
Style de documentation NumPy
import scipy
help(scipy.percentile)
percentile(a, q, axis=None, out=None, overwrite_input=False, interpolation='linear') Compute the q-th percentile of the data along the specified axis. Returns the q-th percentile(s) of the array elements.Parameters ----------a : array_likeInput array or object that can be converted to an array.
Other types include - int, float, bool, str, dict, numpy.array, etc.
Style de documentation NumPy
import scipy
help(scipy.percentile)
percentile(a, q, axis=None, out=None, overwrite_input=False, interpolation='linear')
...
Parameters
----------
...
axis : {int, tuple of int, None}
...
interpolation : {'linear', 'lower', 'higher', 'midpoint', 'nearest'}
- Indiquez plusieurs types pour un paramètre si pertinent
- Énumérez les valeurs acceptées s'il n'y a que quelques options valides
Style de documentation NumPy
import scipy
help(scipy.percentile)
percentile(a, q, axis=None, out=None, overwrite_input=False, interpolation='linear')
...
Returns
-------
percentile : scalar or ndarray
If `q` is a single percentile and `axis=None`, then the result
is a scalar. If multiple percentiles are given, first axis of
the result corresponds to the percentiles...
...
Style de documentation NumPy
Autres sections
RaisesSee AlsoNotesReferencesExamples
1 https://numpydoc.readthedocs.io/en/latest/format.html
Modèles et conversion de style de documentation
pymentpeut générer des docstrings- Exécuter depuis le terminal
- Tout style de documentation parmi
- Numpydoc
- reST (reStructuredText)
- Javadoc (epytext)
- Convertir la documentation d'un style à un autre
Modèles et conversion de style de documentation
pyment -w -o numpydoc textanalysis.py
def count_words(filepath, words_list):
# Open the text file
...
return n
-w- écraser le fichier-o numpydoc- sortie au format NumPy
Modèles et conversion de style de documentation
pyment -w -o numpydoc textanalysis.py
def count_words(filepath, words_list):
"""
Parameters
----------
filepath :
words_list :
Returns
-------
type
"""
Traduire vers le style Google
pyment -w -o google textanalysis.py
def count_words(filepath, words_list):
"""Compter le nombre total d'occurrences de ces mots.
Le calcul est effectué sur un fichier texte à l'emplacement indiqué.
Parameters
----------
filepath : str
Path to text file.
words_list : list of str
Count the total number of appearances of these words.
Returns
-------
"""
Traduire vers le style Google
pyment -w -o google textanalysis.py
def count_words(filepath, words_list):
"""Compter le nombre total d'occurrences de ces mots.
Le calcul est effectué sur un fichier texte à l'emplacement indiqué.
Args:
filepath(str): Path to text file.
words_list(list of str): Count the total number of appearances of these words.
Returns:
"""
Documentation de progiciel, sous-progiciel et module
mysklearn/__init__.py
"""
Régression linéaire pour Python
===============================
mysklearn est un progiciel complet pour implémenter
la régression linéaire en Python.
"""
mysklearn/preprocessing/__init__.py
"""
Un sous-progiciel pour les opérations de prétraitement standard.
"""
mysklearn/preprocessing/normalize.py
"""
Un module pour normaliser les données.
"""
Passons à la pratique !
Créer des paquetages Python
