Tài liệu

Phát triển gói Python

James Fulton

Climate informatics researcher

Vì sao cần tài liệu?

  • Giúp người dùng sử dụng mã của bạn
  • Ghi tài liệu cho từng
    • Hàm
    • Lớp
    • Phương thức lớp
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.
...
Phát triển gói Python

Vì sao cần tài liệu?

  • Giúp người dùng sử dụng mã của bạn
  • Ghi tài liệu cho từng
    • Hàm
    • Lớp
    • Phương thức lớp
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.
...
Phát triển gói Python

Vì sao cần tài liệu?

  • Giúp người dùng sử dụng mã của bạn
  • Ghi tài liệu cho từng
    • Hàm
    • Lớp
    • Phương thức lớp
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.
...
Phát triển gói Python

Tài liệu hàm

def count_words(filepath, words_list):

    """ ... """
Phát triển gói Python

Tài liệu hàm

def count_words(filepath, words_list):

    """Đếm tổng số lần các từ này xuất hiện."""
Phát triển gói Python

Tài liệu hàm

def count_words(filepath, words_list):

    """Đếm tổng số lần các từ này xuất hiện.

    Đếm trên tệp văn bản tại vị trí đã cho.
    """
Phát triển gói Python

Tài liệu hàm

def count_words(filepath, words_list):

    """Đếm tổng số lần các từ này xuất hiện.

    Đếm trên tệp văn bản tại vị trí đã cho.

    [giải thích filepath và words_list là gì]

    [giá trị trả về]
    """
Phát triển gói Python

Phong cách tài liệu

Phong cách tài liệu Google

"""Dòng tóm tắt.

Mô tả mở rộng của hàm.

Args:
    arg1 (int): Mô tả arg1
    arg2 (str): Mô tả arg2

Phong cách NumPy

    """Dòng tóm tắt.

    Mô tả mở rộng của hàm.

    Parameters
    ----------
    arg1 : int
        Mô tả arg1 ...

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

Phong cách reStructuredText

    """Dòng tóm tắt.

    Mô tả mở rộng của hàm.

    :param arg1: Mô tả arg1
    :type arg1: int
    :param arg2: Mô tả arg2
    :type arg2: str

Phong cách Epytext

"""Dòng tóm tắt.

  Mô tả mở rộng của hàm.

  @type arg1: int
  @param arg1:  Mô tả arg1
  @type arg2: str
  @param arg2: Mô tả arg2
Phát triển gói Python

Phong cách tài liệu NumPy

Phổ biến trong các gói Python khoa học như

  • numpy
  • scipy
  • pandas
  • sklearn
  • matplotlib
  • dask
  • v.v.
Phát triển gói Python

Phong cách tài liệu 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.

Các kiểu khác gồm - int, float, bool, str, dict, numpy.array, v.v.

Phát triển gói Python

Phong cách tài liệu 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'}
  • Liệt kê nhiều kiểu cho tham số nếu phù hợp
  • Liệt kê giá trị hợp lệ nếu chỉ có vài lựa chọn
Phát triển gói Python

Phong cách tài liệu 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...
    ...
Phát triển gói Python

Phong cách tài liệu NumPy

Các mục khác

  • Raises
  • See Also
  • Notes
  • References
  • Examples
1 https://numpydoc.readthedocs.io/en/latest/format.html
Phát triển gói Python

Mẫu tài liệu và chuyển đổi phong cách

  • Có thể dùng pyment để tạo docstring
  • Chạy từ terminal
  • Hỗ trợ các phong cách
    • Google
    • Numpydoc
    • reST (reStructuredText)
    • Javadoc (epytext)
  • Chuyển đổi tài liệu giữa các phong cách
Phát triển gói Python

Mẫu tài liệu và chuyển đổi phong cách

pyment -w -o numpydoc textanalysis.py

def count_words(filepath, words_list):
    # Open the text file
    ...
    return n
  • -w - ghi đè tệp
  • -o numpydoc - xuất theo kiểu NumPy
Phát triển gói Python

Mẫu tài liệu và chuyển đổi phong cách

pyment -w -o numpydoc textanalysis.py

def count_words(filepath, words_list):
    """

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

    words_list :


    Returns
    -------
    type
    """
Phát triển gói Python

Chuyển sang kiểu Google

pyment -w -o google textanalysis.py

def count_words(filepath, words_list):
    """Đếm tổng số lần các từ này xuất hiện.

    Đếm trên tệp văn bản tại vị trí đã cho.

    Parameters
    ----------
    filepath : str
        Đường dẫn tới tệp văn bản.
    words_list : list of str
        Đếm tổng số lần xuất hiện của các từ này.

    Returns
    -------

    """
Phát triển gói Python

Chuyển sang kiểu Google

pyment -w -o google textanalysis.py

def count_words(filepath, words_list):
    """Đếm tổng số lần các từ này xuất hiện.

    Đếm trên tệp văn bản tại vị trí đã cho.

    Args:
      filepath(str): Đường dẫn tới tệp văn bản.
      words_list(list of str): Đếm tổng số lần xuất hiện của các từ này.

    Returns:


    """
Phát triển gói Python

Tài liệu gói, gói con và mô-đun

mysklearn/__init__.py

"""
Hồi quy tuyến tính cho Python
=============================

mysklearn là gói hoàn chỉnh để triển khai
hồi quy tuyến tính trong Python. 
"""

mysklearn/preprocessing/__init__.py

"""
Gói con cho các thao tác tiền xử lý chuẩn.
"""

 

mysklearn/preprocessing/normalize.py

"""
Mô-đun để chuẩn hóa dữ liệu.
"""
Phát triển gói Python

Ayo berlatih!

Phát triển gói Python

Preparing Video For Download...