เอกสารประกอบโค้ด

การพัฒนา Python Packages

James Fulton

Climate informatics researcher

ทำไมต้องมีเอกสารประกอบโค้ด?

ช่วยให้ผู้ใช้เข้าใจและใช้งานโค้ดได้
เขียนเอกสารสำหรับแต่ละ
- ฟังก์ชัน
- คลาส
- เมธอดของคลาส

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

ทำไมต้องมีเอกสารประกอบโค้ด?

ช่วยให้ผู้ใช้เข้าใจและใช้งานโค้ดได้
เขียนเอกสารสำหรับแต่ละ
- ฟังก์ชัน
- คลาส
- เมธอดของคลาส

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

ทำไมต้องมีเอกสารประกอบโค้ด?

ช่วยให้ผู้ใช้เข้าใจและใช้งานโค้ดได้
เขียนเอกสารสำหรับแต่ละ
- ฟังก์ชัน
- คลาส
- เมธอดของคลาส

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

เอกสารประกอบฟังก์ชัน

def count_words(filepath, words_list):

    """ ... """

เอกสารประกอบฟังก์ชัน

def count_words(filepath, words_list):

    """Count the total number of times these words appear."""

เอกสารประกอบฟังก์ชัน

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

เอกสารประกอบฟังก์ชัน

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]
    """

รูปแบบเอกสารประกอบโค้ด

รูปแบบ Google

"""Summary line.

Extended description of function.

Args:
    arg1 (int): Description of arg1
    arg2 (str): Description of arg2

รูปแบบ NumPy

    """Summary line.

    Extended description of function.

    Parameters
    ----------
    arg1 : int
        Description of arg1 ...

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

รูปแบบ reStructured text

    """Summary line.

    Extended description of function.

    :param arg1: Description of arg1
    :type arg1: int
    :param arg2: Description of arg2
    :type arg2: str

รูปแบบ Epytext

"""Summary line.

  Extended description of function.

  @type arg1: int
  @param arg1:  Description of arg1
  @type arg2: str
  @param arg2: Description of arg2

รูปแบบเอกสาร NumPy

นิยมใช้ในแพ็กเกจ Python สายวิทยาศาสตร์ เช่น

numpy
scipy
pandas
sklearn
matplotlib
dask
และอื่น ๆ

รูปแบบเอกสาร 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.

ประเภทอื่น ได้แก่ - int, float, bool, str, dict, numpy.array ฯลฯ

รูปแบบเอกสาร 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'}

ระบุหลายประเภทสำหรับพารามิเตอร์ได้หากเหมาะสม
ระบุค่าที่ยอมรับได้หากมีตัวเลือกจำกัด

รูปแบบเอกสาร 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...
    ...

รูปแบบเอกสาร NumPy

หัวข้ออื่น ๆ

Raises
See Also
Notes
References
Examples

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

เทมเพลตและการแปลงรูปแบบเอกสาร

ใช้ pyment สร้าง docstring ได้
รันจาก terminal
รองรับรูปแบบเอกสาร
- Google
- Numpydoc
- reST (reStructured-text)
- Javadoc (epytext)
แปลงรูปแบบเอกสารจากแบบหนึ่งไปอีกแบบได้

เทมเพลตและการแปลงรูปแบบเอกสาร

pyment -w -o numpydoc textanalysis.py

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

-w - เขียนทับไฟล์
-o numpydoc - เอาต์พุตในรูปแบบ NumPy

เทมเพลตและการแปลงรูปแบบเอกสาร

pyment -w -o numpydoc textanalysis.py

def count_words(filepath, words_list):
    """

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

    words_list :


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

แปลงเป็นรูปแบบ 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
    -------

    """

แปลงเป็นรูปแบบ 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:


    """

เอกสารสำหรับแพ็กเกจ ซับแพ็กเกจ และโมดูล

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

มาฝึกกันเถอะ!

การพัฒนา Python Packages