Dokumentasi

Mengembangkan Paket Python

James Fulton

Climate informatics researcher

Mengapa menyertakan dokumentasi?

Membantu pengguna memakai kode Anda
Dokumentasikan setiap
- Fungsi
- Kelas
- Metode kelas

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.
...

Mengapa menyertakan dokumentasi?

Membantu pengguna memakai kode Anda
Dokumentasikan setiap
- Fungsi
- Kelas
- Metode kelas

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.
...

Mengapa menyertakan dokumentasi?

Membantu pengguna memakai kode Anda
Dokumentasikan setiap
- Fungsi
- Kelas
- Metode kelas

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.
...

Dokumentasi fungsi

def count_words(filepath, words_list):

    """ ... """

Dokumentasi fungsi

def count_words(filepath, words_list):

    """Hitung total kemunculan kata-kata ini."""

Dokumentasi fungsi

def count_words(filepath, words_list):

    """Hitung total kemunculan kata-kata ini.

    Perhitungan dilakukan pada berkas teks di lokasi yang diberikan.
    """

Dokumentasi fungsi

def count_words(filepath, words_list):

    """Hitung total kemunculan kata-kata ini.

    Perhitungan dilakukan pada berkas teks di lokasi yang diberikan.

    [jelaskan apa itu filepath dan words_list]

    [apa yang dikembalikan]
    """

Gaya dokumentasi

Gaya dokumentasi Google

"""Baris ringkasan.

Deskripsi fungsi yang lebih panjang.

Args:
    arg1 (int): Deskripsi arg1
    arg2 (str): Deskripsi arg2

Gaya NumPy

    """Baris ringkasan.

    Deskripsi fungsi yang lebih panjang.

    Parameters
    ----------
    arg1 : int
        Deskripsi arg1 ...

    Returns
    ----------
    numpy.ndarray

Gaya reStructured text

    """Baris ringkasan.

    Deskripsi fungsi yang lebih panjang.

    :param arg1: Deskripsi arg1
    :type arg1: int
    :param arg2: Deskripsi arg2
    :type arg2: str

Gaya Epytext

"""Baris ringkasan.

  Deskripsi fungsi yang lebih panjang.

  @type arg1: int
  @param arg1:  Deskripsi arg1
  @type arg2: str
  @param arg2: Deskripsi arg2

Gaya dokumentasi NumPy

Populer di paket Python ilmiah seperti

numpy
scipy
pandas
sklearn
matplotlib
dask
dll.

Gaya dokumentasi 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_like

        Input array or object that can be converted to an array.

Tipe lain meliputi - int, float, bool, str, dict, numpy.array, dll.

Gaya dokumentasi 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'}

Cantumkan beberapa tipe untuk parameter bila perlu
Cantumkan nilai yang diterima jika opsinya sedikit

Gaya dokumentasi 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...
    ...

Gaya dokumentasi NumPy

Bagian lain

Raises
See Also
Notes
References
Examples

¹ https://numpydoc.readthedocs.io/en/latest/format.html

Templat dokumentasi dan terjemahan gaya

pyment dapat digunakan untuk membuat docstring
Jalankan dari terminal
Gaya dokumentasi apa pun dari
- Google
- Numpydoc
- reST (reStructuredText)
- Javadoc (epytext)
Ubah dokumentasi dari satu gaya ke gaya lain

Templat dokumentasi dan terjemahan gaya

pyment -w -o numpydoc textanalysis.py

def count_words(filepath, words_list):
    # Open the text file
    ...
    return n

-w - timpa berkas
-o numpydoc - keluaran gaya NumPy

Templat dokumentasi dan terjemahan gaya

pyment -w -o numpydoc textanalysis.py

def count_words(filepath, words_list):
    """

    Parameters
    ----------
    filepath :

    words_list :


    Returns
    -------
    type
    """

Terjemahkan ke gaya Google

pyment -w -o google textanalysis.py

def count_words(filepath, words_list):
    """Hitung total kemunculan kata-kata ini.

    Perhitungan dilakukan pada berkas teks di lokasi yang diberikan.

    Parameters
    ----------
    filepath : str
        Path ke berkas teks.
    words_list : list of str
        Hitung total kemunculan kata-kata ini.

    Returns
    -------

    """

Terjemahkan ke gaya Google

pyment -w -o google textanalysis.py

def count_words(filepath, words_list):
    """Hitung total kemunculan kata-kata ini.

    Perhitungan dilakukan pada berkas teks di lokasi yang diberikan.

    Args:
      filepath(str): Path ke berkas teks.
      words_list(list of str): Hitung total kemunculan kata-kata ini.

    Returns:


    """

Dokumentasi paket, subpaket, dan modul

mysklearn/__init__.py

"""
Regresi linear untuk Python
============================

mysklearn adalah paket lengkap untuk mengimplementasikan
regresi linear di Python. 
"""

mysklearn/preprocessing/__init__.py

"""
Subpaket untuk operasi prapemrosesan standar.
"""

mysklearn/preprocessing/normalize.py

"""
Modul untuk menormalisasi data.
"""

Ayo berlatih!

Mengembangkan Paket Python