Tôi đã thấy một vài phong cách viết tài liệu khác nhau trong Python, đó là một phong cách chính thức hay "đồng ý"?

Các định dạng

Tài liệu Python có thể được viết theo một số định dạng như các bài viết khác cho thấy. Tuy nhiên, định dạng chuỗi Sphinx mặc định không được đề cập và dựa trên reSturationuredText (reST) . Bạn có thể nhận được một số thông tin về các định dạng chính trong bài đăng trên blog này .

Lưu ý rằng reST được khuyến nghị bởi PEP 287

Có các định dạng được sử dụng chính cho các tài liệu.

- Epytext

Trong lịch sử, một phong cách giống như javadoc là phổ biến, do đó, nó được lấy làm cơ sở cho Epydoc (với Epytextđịnh dạng được gọi ) để tạo tài liệu.

Thí dụ:

"""
This is a javadoc style.

@param param1: this is a first param
@param param2: this is a second param
@return: this is a description of what is returned
@raise keyError: raises an exception
"""

- nghỉ ngơi

Ngày nay, các định dạng có thể phổ biến hơn là reStructuredText (phần còn lại) định dạng được sử dụng bởi Sphinx để tạo ra tài liệu. Lưu ý: nó được sử dụng theo mặc định trong JetBrains PyCharm (nhập ba dấu ngoặc kép sau khi xác định phương thức và nhấn enter). Nó cũng được sử dụng theo mặc định như định dạng đầu ra trong Pyment.

Thí dụ:

"""
This is a reST style.

:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""

- Google

Google có định dạng riêng thường được sử dụng. Nó cũng có thể được giải thích bởi Sphinx (tức là sử dụng plugin Napoleon ).

Thí dụ:

"""
This is an example of Google style.

Args:
    param1: This is the first param.
    param2: This is a second param.

Returns:
    This is a description of what is returned.

Raises:
    KeyError: Raises an exception.
"""

Thậm chí nhiều ví dụ

- Numpydoc

Lưu ý rằng Numpy khuyên bạn nên theo Numpydoc của riêng họ dựa trên định dạng của Google và Sphinx có thể sử dụng được.

"""
My numpydoc description of a kind
of very exhautive numpydoc format docstring.

Parameters
----------
first : array_like
    the 1st param name `first`
second :
    the 2nd param
third : {'value', 'other'}, optional
    the 3rd param, by default 'value'

Returns
-------
string
    a value in a string

Raises
------
KeyError
    when a key error
OtherError
    when an other error
"""

Chuyển đổi / tạo

Có thể sử dụng một công cụ như Pyment để tự động tạo tài liệu cho dự án Python chưa được ghi lại hoặc để chuyển đổi các tài liệu hiện có (có thể trộn một số định dạng) từ định dạng sang định dạng khác.

Lưu ý: Các ví dụ được lấy từ tài liệu Pyment

Các hướng dẫn phong cách Google chứa một hướng dẫn phong cách tuyệt vời Python. Nó bao gồm các quy ước cho cú pháp chuỗi có thể đọc được cung cấp hướng dẫn tốt hơn PEP-257. Ví dụ:

def square_root(n):
    """Calculate the square root of a number.

    Args:
        n: the number to get the square root of.
    Returns:
        the square root of n.
    Raises:
        TypeError: if n is not a number.
        ValueError: if n is negative.

    """
    pass

Tôi muốn mở rộng điều này để bao gồm thông tin loại trong các đối số, như được mô tả trong hướng dẫn tài liệu Nhân sư này . Ví dụ:

def add_value(self, value):
    """Add a new value.

       Args:
           value (str): the value to add.
    """
    pass

Các quy ước về chuỗi trong PEP-257 với nhiều chi tiết hơn PEP-8.

Tuy nhiên, các tài liệu dường như mang tính cá nhân hơn nhiều so với các lĩnh vực mã khác. Các dự án khác nhau sẽ có tiêu chuẩn riêng của họ.

Tôi có xu hướng luôn luôn bao gồm các tài liệu, bởi vì chúng có xu hướng thể hiện cách sử dụng chức năng và những gì nó làm rất nhanh.

Tôi thích giữ mọi thứ nhất quán, bất kể độ dài của chuỗi. Tôi thích làm thế nào để mã trông khi thụt lề và khoảng cách là nhất quán. Điều đó có nghĩa là, tôi sử dụng:

def sq(n):
    """
    Return the square of n. 
    """
    return n * n

Kết thúc:

def sq(n):
    """Returns the square of n."""
    return n * n

Và có xu hướng bỏ bình luận về dòng đầu tiên trong các tài liệu dài hơn:

def sq(n):
    """
    Return the square of n, accepting all numeric types:

    >>> sq(10)
    100

    >>> sq(10.434)
    108.86835599999999

    Raises a TypeError when input is invalid:

    >>> sq(4*'435')
    Traceback (most recent call last):
      ...
    TypeError: can't multiply sequence by non-int of type 'str'

    """
    return n*n

Có nghĩa là tôi thấy các tài liệu bắt đầu như thế này là lộn xộn.

def sq(n):
    """Return the squared result. 
    ...

Như một cách thận trọng, không ai đề cập đến nó: bạn cũng có thể sử dụng Tiêu chuẩn Chuỗi Numpy . Nó được sử dụng rộng rãi trong cộng đồng khoa học.

• Các đặc điểm kỹ thuật của định dạng từ numpy cùng với một ví dụ
• Bạn có một phần mở rộng nhân sư để kết xuất nó: numpydoc
• Và một ví dụ về việc một chuỗi doc được hiển thị có thể trông như thế nào: http://docs.scipy.org/doc/numpy/reference/generated/numpy.mean.html

Tiện ích mở rộng nhân sư Napolean để phân tích các tài liệu kiểu Google (được đề xuất trong câu trả lời của @Nathan) cũng hỗ trợ chuỗi tài liệu theo kiểu Numpy và so sánh ngắn cả hai.

Và cuối cùng là một ví dụ cơ bản để đưa ra một ý tưởng như thế nào:

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Parameters
    ----------
    arg1 : int
        Description of arg1
    arg2 : str
        Description of arg2

    Returns
    -------
    bool
        Description of return value

    See Also
    --------
    otherfunc : some related other function

    Examples
    --------
    These are written in doctest format, and should illustrate how to
    use the function.

    >>> a=[1,2,3]
    >>> print [x + 3 for x in a]
    [4, 5, 6]
    """
    return True

PEP-8 là tiêu chuẩn mã hóa python chính thức. Nó chứa một phần về các tài liệu, trong đó đề cập đến PEP-257 - một đặc điểm kỹ thuật hoàn chỉnh cho các tài liệu.

Đó là Python; bất cứ điều gì đi . Xem xét làm thế nào để xuất bản tài liệu của bạn . Tài liệu là vô hình ngoại trừ độc giả của mã nguồn của bạn.

Mọi người thực sự thích duyệt và tìm kiếm tài liệu trên web. Để đạt được điều đó, hãy sử dụng công cụ tài liệu Sphinx . Đó là tiêu chuẩn thực tế để ghi lại các dự án Python. Sản phẩm này rất đẹp - hãy xem https://python-guide.readthedocs.org/en/latest/ . Trang web Đọc Tài liệu sẽ lưu trữ tài liệu của bạn miễn phí.

Tôi đề nghị sử dụng Vladimir Keleshev của pep257 chương trình Python để kiểm tra docstrings của bạn chống lại PEP-257 và docstring Chuẩn NumPy để mô tả các thông số, lợi nhuận, vv

pep257 sẽ báo cáo phân kỳ bạn thực hiện từ tiêu chuẩn và được gọi là pylint và pep8.