什麼是標準的Python文檔字符串格式?


Answers

Google風格指南包含一個非常棒的Python風格指南。 它包含可讀文檔字符串語法的約定,它比PEP-257提供更好的指導。 例如:

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

我喜歡將其擴展為在參數中包含類型信息,如Sphinx文檔教程中所述 。 例如:

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

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

我在Python中看到了幾種不同的文檔編寫風格,是否有官方的或“協議式”的風格?




正如沒有人提到它:你也可以使用Numpy Docstring Standard 。 它在科學界被廣泛使用。

用於解析Google風格文檔字符串(在@Nathan的答案中推薦)的Napolean sphinx擴展也支持Numpy風格的文檔字符串,並對兩者進行簡短comparison

最後給出一個基本示例來說明它的外觀:

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



它是Python; 什麼都可以 。 考慮如何發布您的文檔 。 除了源代碼的讀者以外,Docstrings是不可見的。

人們非常喜歡在網絡上瀏覽和搜索文檔。 要做到這一點,請使用文檔工具Sphinx 。 這是記錄Python項目的事實標準。 該產品很漂亮 - 看看https://python-guide.readthedocs.org/en/latest/閱讀文檔網站將免費託管您的文檔。