Cách tạo tài liệu cho hàm Python (docstring & Sphinx)

Thông tin về hàm được đặt trong docstring (chuỗi tài liệu) ngay sau dòng def.

Quy tắc viết docstring (theo PEP 257)

• Dòng đầu: Tóm tắt ngắn gọn, bắt đầu bằng chữ hoa, kết thúc bằng dấu chấm. Không nhắc tên hàm.
• Dòng thứ 2: Để trống (tách tóm tắt và mô tả chi tiết).
• Các dòng sau: Mô tả chi tiết tham số, trả về, ngoại lệ, ví dụ...

Ví dụ docstring chuẩn

def add(a, b):
    """Trả về tổng của hai số.

    Args:
        a (int/float): Số thứ nhất.
        b (int/float): Số thứ hai.

    Returns:
        int/float: Tổng a + b.

    Raises:
        TypeError: Nếu a, b không phải số.
    """
    return a + b

Sphinx - Công cụ tạo tài liệu phổ biến nhất

• Chuyển đổi reStructuredText (.rst) sang HTML, PDF (LaTeX), man pages, text...
• Tự động trích xuất signature và docstring từ code Python (introspection).
• Hỗ trợ cross-reference, indexing, theme tùy chỉnh.

Các định dạng docstring phổ biến

• reStructuredText (reST) - mặc định của Sphinx.
• Google Style - dễ đọc, ngắn gọn.
• NumPy Style - chi tiết, phổ biến trong khoa học dữ liệu.

Mẹo: Dùng help(function) hoặc function.__doc__ để xem docstring trong REPL.