Dokumentacja
Tworzenie pakietów w Pythonie
James Fulton
Climate informatics researcher
Dlaczego warto pisać dokumentację?
- Pomaga użytkownikom korzystać z kodu
- Dokumentować każdy
- Funkcję
- Klasę
- Metodę klasy
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.
...
Dlaczego warto pisać dokumentację?
- Pomaga użytkownikom korzystać z kodu
- Dokumentować każdy
- Funkcję
- Klasę
- Metodę klasy
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.
...
Dlaczego warto pisać dokumentację?
- Pomaga użytkownikom korzystać z kodu
- Dokumentować każdy
- Funkcję
- Klasę
- Metodę klasy
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.
...
Dokumentacja funkcji
def count_words(filepath, words_list):""" ... """
Dokumentacja funkcji
def count_words(filepath, words_list):"""Count the total number of times these words appear."""
Dokumentacja funkcji
def count_words(filepath, words_list):"""Count the total number of times these words appear. The count is performed on a text file at the given location. """
Dokumentacja funkcji
def count_words(filepath, words_list):"""Count the total number of times these words appear. The count is performed on a text file at the given location. [explain what filepath and words_list are] [what is returned] """
Style dokumentacji
Styl dokumentacji Google
"""Summary line.
Extended description of function.
Args:
arg1 (int): Description of arg1
arg2 (str): Description of arg2
Styl NumPy
"""Summary line.
Extended description of function.
Parameters
----------
arg1 : int
Description of arg1 ...
Returns
----------
numpy.ndarray
Styl reStructuredText
"""Summary line.
Extended description of function.
:param arg1: Description of arg1
:type arg1: int
:param arg2: Description of arg2
:type arg2: str
Styl Epytext
"""Summary line.
Extended description of function.
@type arg1: int
@param arg1: Description of arg1
@type arg2: str
@param arg2: Description of arg2
Styl dokumentacji NumPy
Popularne w naukowych pakietach Pythona, np.
numpyscipypandassklearnmatplotlibdask- itd.
Styl dokumentacji 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.
Inne typy to m.in. int, float, bool, str, dict, numpy.array itd.
Styl dokumentacji 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'}
- Podawaj wiele typów parametru, jeśli to zasadne
- Podawaj dopuszczalne wartości, jeśli opcji jest niewiele
Styl dokumentacji 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...
...
Styl dokumentacji NumPy
Inne sekcje
RaisesSee AlsoNotesReferencesExamples
1 https://numpydoc.readthedocs.io/en/latest/format.html
Szablony dokumentacji i konwersja stylów
pymentumożliwia generowanie docstringów- Uruchamiany z terminala
- Obsługuje style dokumentacji
- Numpydoc
- reST (reStructuredText)
- Javadoc (Epytext)
- Konwertuje dokumentację między stylami
Szablony dokumentacji i konwersja stylów
pyment -w -o numpydoc textanalysis.py
def count_words(filepath, words_list):
# Open the text file
...
return n
-w– nadpisanie pliku-o numpydoc– wynik w stylu NumPy
Szablony dokumentacji i konwersja stylów
pyment -w -o numpydoc textanalysis.py
def count_words(filepath, words_list):
"""
Parameters
----------
filepath :
words_list :
Returns
-------
type
"""
Konwersja do stylu Google
pyment -w -o google textanalysis.py
def count_words(filepath, words_list):
"""Count the total number of times these words appear.
The count is performed on a text file at the given location.
Parameters
----------
filepath : str
Path to text file.
words_list : list of str
Count the total number of appearances of these words.
Returns
-------
"""
Konwersja do stylu Google
pyment -w -o google textanalysis.py
def count_words(filepath, words_list):
"""Count the total number of times these words appear.
The count is performed on a text file at the given location.
Args:
filepath(str): Path to text file.
words_list(list of str): Count the total number of appearances of these words.
Returns:
"""
Dokumentacja pakietów, podpakietów i modułów
mysklearn/__init__.py
"""
Linear regression for Python
============================
mysklearn is a complete package for implmenting
linear regression in python.
"""
mysklearn/preprocessing/__init__.py
"""
A subpackage for standard preprocessing operations.
"""
mysklearn/preprocessing/normalize.py
"""
A module for normalizing data.
"""
Czas na ćwiczenia!
Tworzenie pakietów w Pythonie
