Hướng dẫn Docstring trong Python: Ví dụ & Định dạng cho Pydoc, Numpy, Sphinx Doc Strings

Nếu bạn vừa bắt đầu học Python và muốn tìm hiểu thêm, hãy tham gia khóa học Giới thiệu Khoa học Dữ liệu với Python của DataCamp.

Luyện tập Docstring trong Python với bài tập thực hành này.

Docstring trong Python là gì? 

Chuỗi tài liệu trong Python, thường gọi là docstring, là một chuỗi ký tự (string literal) dùng trong định nghĩa lớp, mô-đun, hàm hoặc phương thức. Docstring có thể truy cập qua thuộc tính doc (__doc__) của bất kỳ đối tượng Python nào và cả bằng hàm dựng sẵn help(). Docstring của một đối tượng được xác định bằng cách đưa một hằng chuỗi vào làm câu lệnh đầu tiên trong định nghĩa của đối tượng đó.

Không giống chú thích (comment) thông thường, vốn giải thích từng dòng mã, docstring đưa ra mô tả cấp cao về chức năng của một hàm, lớp hoặc mô-đun. Docstring được viết tốt sẽ nâng cao tính dễ đọc của mã, khả năng bảo trì, và hợp tác, khiến chúng trở thành thực hành tốt để viết tài liệu cho mã Python của bạn với tư cách là nhà phát triển Python.

Docstring giúp bạn hiểu khả năng của một mô-đun hoặc hàm. Ví dụ, giả sử bạn đã cài thư viện scikit-learn và muốn biết mọi thứ về gói sklearn như mô tả, các mô-đun trong gói, v.v., bạn chỉ cần dùng hàm help để lấy toàn bộ thông tin.

Hãy nhanh chóng import gói này.

import sklearn

help(sklearn)

Bạn sẽ thấy một kết quả tương tự như dưới đây:

Docstring trong Python so với Comment

Docstring có tinh thần tương tự comment, nhưng là phiên bản nâng cao, hợp lý và hữu ích hơn. Docstring đóng vai trò là tài liệu cho lớp, mô-đun và gói.

Ngược lại, comment chủ yếu dùng để giải thích những phần mã không hiển nhiên và hữu ích cho việc ghi chú về sửa lỗi hoặc các tác vụ cần làm.

Docstring được viết bằng cặp dấu nháy mở & đóng, trong khi comment bắt đầu bằng ký tự #.

Lưu ý rằng comment không thể truy cập bằng thuộc tính dựng sẵn doc và hàm help. Hãy xem điều gì xảy ra nếu bạn thử làm như vậy:

def string_reverse(str1):
    #Returns the reversed String.

    #Parameters:
    #    str1 (str):The string which is to be reversed.

    #Returns:
    #    reverse(str1):The string which gets reversed.   

    reverse_str1 = ''
    i = len(str1)
    while i > 0:
        reverse_str1 += str1[i - 1]
        i = i- 1
    return reverse_str1

print(string_reverse.__doc__)

None

help(string_reverse)

Help on function string_reverse in module __main__:

string_reverse(str1)

Có vài cách để viết hoặc dùng Docstring, tức là docstring một dòng và docstring nhiều dòng. Hãy tìm hiểu lần lượt.

Docstring Một Dòng

Docstring một dòng là mô tả ngắn gọn nằm trọn trong một dòng. Chúng được bao bởi ba dấu nháy (''' hoặc """), và dấu nháy đóng phải ở cùng dòng.

Dù cả ba nháy đơn và ba nháy kép đều dùng được, quy ước chuẩn trong Python là dùng ba nháy kép (""").

Ví dụ: 

def square(a):
    """Returns the square of the given number."""
    return a ** 2  # Corrected exponentiation

# Accessing the docstring
print(square.__doc__)

Kết quả:

Returns the square of the given number.

Bạn cũng có thể lấy tài liệu này bằng hàm help() của Python:

help(square)

Kết quả:

Help on function square in module __main__:

square(a)
    Returns the square of the given number.

Docstring Nhiều Dòng

Docstring nhiều dòng cũng chứa chuỗi ký tự như Docstring một dòng, nhưng theo sau là một dòng trống và phần văn bản mô tả.

Định dạng chung để viết Docstring nhiều dòng như sau:

def some_function(argument1):
    """Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value

   """

    return argument1

print(some_function.__doc__)

Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value

help(some_function)

Help on function some_function in module __main__:

some_function(argument1)
    Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value

Hãy xem ví dụ sau để thấy cách dùng chuỗi nhiều dòng một cách chi tiết:

def string_reverse(str1):
    '''
    Returns the reversed String.

    Parameters:
        str1 (str):The string which is to be reversed.

    Returns:
        reverse(str1):The string which gets reversed.   
    '''

    reverse_str1 = ''
    i = len(str1)
    while i > 0:
        reverse_str1 += str1[i - 1]
        i = i- 1
    return reverse_str1

print(string_reverse('DeepLearningDataCamp'))

pmaCataDgninraeLpeeD

help(string_reverse)

Help on function string_reverse in module __main__:

string_reverse(str1)
    Returns the reversed String.

    Parameters:
        str1 (str):The string which is to be reversed.

    Returns:
        reverse(str1):The string which gets reversed.

Bạn có thể thấy ở trên rằng dòng tóm tắt nằm trên một dòng và được tách khỏi nội dung khác bằng một dòng trống. Cần tuân theo quy ước này vì nó hữu ích cho các công cụ lập chỉ mục tự động.

Docstring Dựng sẵn trong Python

Hãy xem các Docstring dựng sẵn của Python.

Tất cả hàm, lớp, phương thức dựng sẵn đều có mô tả cho con người đính kèm. Bạn có thể truy cập theo hai cách.

• thuộc tính doc
• hàm help

Bạn sẽ nhận thấy đầu ra của hàm help chi tiết hơn thuộc tính __doc__.

Ví dụ:

import math
print(math.__doc__)

This module provides access to the mathematical functions
defined by the C standard.

Tương tự, bạn có thể dùng hàm help:

help(math)

Docstring trong Python cho Lớp (Classes)

Trong định nghĩa lớp, docstring có thể dùng để cung cấp tài liệu cho toàn bộ lớp. Thông thường bạn đặt nó ngay sau phần định nghĩa lớp và bao bằng ba dấu nháy ("""). Ví dụ:

class MyClass:
    """This is the documentation for MyClass."""

    def __init__(self):
        """This is the documentation for the __init__ method."""
        pass

Docstring có thể truy cập bằng thuộc tính __doc__ của lớp hoặc phương thức. Ví dụ, bạn có thể truy cập docstring của MyClass bằng MyClass.__doc__.

Giờ hãy xem một số Định dạng Docstring phổ biến và tìm hiểu chi tiết.

Định dạng Docstring trong Python

Có nhiều định dạng Docstring, nhưng tốt nhất nên dùng các định dạng được trình phân tích Docstring và đồng nghiệp/kỹ sư dữ liệu khác dễ dàng nhận biết. Không có quy tắc bắt buộc khi chọn định dạng Docstring, nhưng cần nhất quán dùng cùng một định dạng xuyên suốt dự án. Ngoài ra, bạn nên ưu tiên định dạng được Sphinx hỗ trợ nhiều.

Các định dạng phổ biến nhất được liệt kê dưới đây.

Có thể có nhiều chuỗi tài liệu khác nhau. Bạn không cần lo lắng rằng phải “phát minh lại bánh xe” để học hết. Các định dạng của những chuỗi tài liệu này gần như tương tự nhau. Mẫu thức giống nhau, chỉ có những khác biệt nhỏ ở mỗi định dạng. Bạn sẽ xem ví dụ về một định dạng phổ biến của chuỗi tài liệu kèm cách dùng.

Đầu tiên, bạn sẽ xem kỹ phong cách Sphinx, sau đó có thể dễ dàng theo các định dạng khác.

Phong cách Sphinx

Sphinx là phong cách đơn giản và truyền thống, diễn đạt đầy đủ, ban đầu được tạo riêng cho Tài liệu Python. Sphinx dùng reStructuredText, tương tự cách dùng Markdown.

class Vehicle(object):
    '''
    The Vehicle object contains lots of vehicles
    :param arg: The arg is used for ...
    :type arg: str
    :param `*args`: The variable arguments are used for ...
    :param `**kwargs`: The keyword arguments are used for ...
    :ivar arg: This is where we store arg
    :vartype arg: str
    '''


    def __init__(self, arg, *args, **kwargs):
        self.arg = arg

    def cars(self, distance, destination):
        '''We can't travel a certain distance in vehicles without fuels, so here's the fuels

        :param distance: The amount of distance traveled
        :type amount: int
        :param bool destinationReached: Should the fuels be refilled to cover required distance?
        :raises: :class:`RuntimeError`: Out of fuel

        :returns: A Car mileage
        :rtype: Cars
        '''  
        pass

Sphinx dùng từ khóa (từ dành riêng); hầu hết ngôn ngữ lập trình đều có. Nhưng trong Sphinx, nó được gọi rõ là role. Trong đoạn mã trên, Sphinx có param là một role, và type là một role, đây là kiểu dữ liệu Sphinx cho param. Role type là tùy chọn, nhưng param là bắt buộc. Các role trả về dùng để ghi tài liệu cho đối tượng được trả về. Nó khác với role param. Role trả về không phụ thuộc vào rtype và ngược lại. rtype là kiểu đối tượng được trả về từ hàm đã cho.

Phong cách Google

Phong cách Google dễ và trực quan hơn khi dùng. Có thể dùng cho tài liệu ngắn hơn. Cần cấu hình tệp python để bắt đầu, cụ thể bạn cần thêm sphinx.ext.napoleon hoặc sphinxcontrib.napoleon vào danh sách extensions trong conf.py.

class Vehicles(object):
    '''
    The Vehicle object contains a lot of vehicles

    Args:
        arg (str): The arg is used for...
        *args: The variable arguments are used for...
        **kwargs: The keyword arguments are used for...

    Attributes:
        arg (str): This is where we store arg,
    '''
    def __init__(self, arg, *args, **kwargs):
        self.arg = arg

    def cars(self, distance,destination):
        '''We can't travel distance in vehicles without fuels, so here is the fuels

        Args:
            distance (int): The amount of distance traveled
            destination (bool): Should the fuels refilled to cover the distance?

        Raises:
            RuntimeError: Out of fuel

        Returns:
            cars: A car mileage
        '''
        pass

Phong cách Google tốt hơn Sphinx. Tuy nhiên, có một điểm bất tiện là trong đoạn mã trên, phần mô tả nhiều dòng cho distance sẽ trông lộn xộn. Vì vậy Numpy có thể được dùng cho dạng tài liệu dài hơn.

Phong cách Numpy

Phong cách Numpy có rất nhiều chi tiết trong tài liệu. Nó diễn đạt đầy đủ hơn các kiểu tài liệu khác, nhưng là lựa chọn tuyệt vời nếu bạn muốn viết tài liệu chi tiết, tức là tài liệu mở rộng cho mọi hàm và tham số.

class Vehicles(object):
    '''
    The Vehicles object contains lots of vehicles

    Parameters
    ----------
    arg : str
        The arg is used for ...
    *args
        The variable arguments are used for ...
    **kwargs
        The keyword arguments are used for ...

    Attributes
    ----------
    arg : str
        This is where we store arg,
    '''
    def __init__(self, arg, *args, **kwargs):
        self.arg = arg

    def cars(self, distance, destination):
        '''We can't travel distance in vehicles without fuels, so here is the fuels

        Parameters
        ----------
        distance : int
            The amount of distance traveled
        destination : bool
            Should the fuels refilled to cover the distance?

        Raises
        ------
        RuntimeError
            Out of fuel

        Returns
        -------
        cars
            A car mileage
        '''
        pass

Ví dụ trên diễn đạt đầy đủ hơn bất kỳ kiểu tài liệu nào khác. Nó dài hơn và chỉ nên dùng cho tài liệu dài và chi tiết.

PyDoc

Như bạn đã biết, docstring có thể truy cập qua thuộc tính dựng sẵn __doc__ của Python và hàm help(). Bạn cũng có thể dùng mô-đun dựng sẵn Pydoc, rất khác về tính năng & chức năng so với thuộc tính doc và hàm help.

Pydoc rất hữu ích khi bạn muốn chia sẻ mã với đồng nghiệp hoặc mở nguồn, khi đó bạn hướng tới lượng người dùng rộng hơn. Nó có thể tạo trang web từ tài liệu Python của bạn và cũng có thể mở máy chủ web.

Hãy xem nó hoạt động thế nào.

Cách dễ nhất và tiện nhất để chạy mô-đun Pydoc là chạy như một script. Để chạy trong ô jupyter lab, bạn sẽ dùng ký tự chấm than (!).

• Pydoc như một mô-đun

!python -m pydoc

pydoc - the Python documentation tool

pydoc <name> ...
    Show text documentation on something.  <name> may be the name of a
    Python keyword, topic, function, module, or package, or a dotted
    reference to a class or function within a module or module in a
    package.  If <name> contains a '\', it is used as the path to a
    Python source file to document. If name is 'keywords', 'topics',
    or 'modules', a listing of these things is displayed.

pydoc -k <keyword>
    Search for a keyword in the synopsis lines of all available modules.

pydoc -n <hostname>
    Start an HTTP server with the given hostname (default: localhost).

pydoc -p <port>
    Start an HTTP server on the given port on the local machine.  Port
    number 0 can be used to get an arbitrary unused port.

pydoc -b
    Start an HTTP server on an arbitrary unused port and open a Web browser
    to interactively browse documentation.  This option can be used in
    combination with -n and/or -p.

pydoc -w <name> ...
    Write out the HTML documentation for a module to a file in the current
    directory.  If <name> contains a '\', it is treated as a filename; if
    it names a directory, documentation is written for all the contents.

Nếu bạn xem kết quả trên, cách dùng đầu tiên của Pydoc là hiển thị tài liệu văn bản về một hàm, mô-đun, lớp, v.v., vậy hãy xem bạn có thể tận dụng điều đó tốt hơn hàm help như thế nào.

!python -m pydoc glob

Help on module glob:

NAME
    glob - Filename globbing utility.

MODULE REFERENCE
    https://docs.python.org/3.7/library/glob

    The following documentation is automatically generated from the Python
    source files.  It may be incomplete, incorrect or include features that
    are considered implementation detail and may vary between Python
    implementations.  When in doubt, consult the module reference at the
    location listed above.

FUNCTIONS
    escape(pathname)
        Escape all special characters.

    glob(pathname, *, recursive=False)
        Return a list of paths matching a pathname pattern.

        The pattern may contain simple shell-style wildcards a la
        fnmatch. However, unlike fnmatch, filenames starting with a
        dot are special cases that are not matched by '*' and '?'
        patterns.

        If recursive is true, the pattern '**' will match any files and
        zero or more directories and subdirectories.

    iglob(pathname, *, recursive=False)
        Return an iterator which yields the paths matching a pathname pattern.

        The pattern may contain simple shell-style wildcards a la
        fnmatch. However, unlike fnmatch, filenames starting with a
        dot are special cases that are not matched by '*' and '?'
        patterns.

        If recursive is true, the pattern '**' will match any files and
        zero or more directories and subdirectories.

DATA
    __all__ = ['glob', 'iglob', 'escape']

FILE
    c:\users\hda3kor\.conda\envs\test\lib\glob.py

Bây giờ, hãy trích xuất tài liệu của glob bằng hàm help.

help(glob)

---------------------------------------------------------------------------

NameError                                 Traceback (most recent call last)

<ipython-input-6-6f504109e3a2> in <module>
----> 1 help(glob)


NameError: name 'glob' is not defined

Như bạn thấy, nó ném lỗi name error vì glob chưa được định nghĩa. Vậy để dùng hàm help nhằm trích xuất tài liệu, trước tiên bạn cần import mô-đun đó, điều mà Pydoc không yêu cầu.

• Pydoc như một dịch vụ web

Hãy khám phá tính năng thú vị nhất của mô-đun Pydoc, tức là chạy Pydoc như một dịch vụ web.

Để làm điều này, bạn chỉ cần chạy Pydoc như một script nhưng với tham số -b để khởi động máy chủ HTTP trên một cổng trống bất kỳ và mở trình duyệt web để duyệt tài liệu tương tác. Điều này hữu ích đặc biệt khi bạn có nhiều dịch vụ khác đang chạy trên hệ thống và không nhớ cổng nào đang rảnh.

!python -m pydoc -b

^C

Ngay khi bạn chạy ô trên, một cửa sổ mới sẽ mở ở một số cổng bất kỳ, và trình duyệt web sẽ trông tương tự như dưới đây.

Hãy xem tài liệu của mô-đun h5py, đây là định dạng tệp dùng để lưu trọng số của kiến trúc mạng nơ-ron.

So sánh các định dạng docstring 

Trong bảng dưới đây, bạn có thể xem so sánh các loại định dạng docstring đã đề cập ở trên: 

• Phong cách Sphinx: Thường dùng trong các dự án lớn cần tài liệu toàn diện. Tích hợp tốt với trình tạo tài liệu của Sphinx.
• Phong cách Google: Lý tưởng cho dự án ưu tiên sự đơn giản và dễ đọc, đặc biệt trong tổ chức dùng hướng dẫn phong cách của Google.
• Phong cách NumPy: Phù hợp nhất với dự án cần tài liệu chi tiết và mở rộng, thường gặp trong khoa học dữ liệu và tính toán khoa học.
• PyDoc: Hữu ích để tạo tài liệu văn bản và HTML, nhưng thiếu cấu trúc như các định dạng khác.

Kết luận

Chúc mừng bạn đã hoàn thành hướng dẫn docstring trong Python.

Hướng dẫn này chủ yếu giúp bạn bắt đầu với docstring bằng cách bao quát các chủ đề thiết yếu. Tuy nhiên, Docstring là một chủ đề rộng và có thể còn một số khái niệm chưa được khám phá. Nếu muốn học thêm, hãy xem hướng dẫn chuỗi (string) trong Python và khóa học viết hàm trong Python của chúng tôi.

Nếu bạn vừa bắt đầu học Python và muốn tìm hiểu thêm, hãy tham gia khóa học Giới thiệu Khoa học Dữ liệu với Python của DataCamp. Bạn cũng có thể theo một trong các lộ trình nghề nghiệp về Python và bắt đầu hành trình trở thành Lập trình viên Python hoặc Nhà khoa học dữ liệu với Python.