3 种不同的 Python 文档字符串格式

Python/ target=_blank class=infotextkey>Python 正在成为当今流行的编程语言。 对于任何编码项目，文档是提高代码可读性的最重要部分，但同时也是最被忽略的部分！ 为了解决这个问题，Sphinx 工具派上用场了，它可以自动化文档部分

现在您已经了解 Sphinx 并知道如何使用它。 让我们知道最常用的文档字符串格式，即 google、NumPy 和 Sphinx 文档字符串格式。

1.Google Docstring

这种文档字符串格式是可汗学院推荐的，俗称“Google Docstring”。 为了确保文档字符串与 Sphinx 兼容并被 Sphinx 的自动文档识别，请在 conf.py 文件中添加 sphinx.ext.napoleon 扩展名。 文档字符串格式为：

def google_docstrings(num1, num2
                      ) -> int:
    """Add up two integer numbers.

    This function simply wraps the ``+`` operator, and does not
    do anything interesting, except for illustrating what
    the docstring of a very simple function looks like.

    Args:
        num1 (int) : First number to add.
        num2 (int) : Second number to add.

    Returns:
        The sum of ``num1`` and ``num2``.

    Raises:
        AnyError: If anything bad hAppens.
    """
    return num1 + num2

2. NumPy 文档字符串

这种文档格式用于 NumPy、SciPy 和 Pandas 等主要数据科学库。 就像 Google 的文档字符串一样，要使其与 Sphinx 兼容，您必须在 conf.py 文件中添加 sphinx.ext.napoleon 扩展名。 文档字符串的格式为：

def numpy_docstrings(num1, num2) -> int:
    """
    Add up two integer numbers.

    This function simply wraps the ``+`` operator, and does not
    do anything interesting, except for illustrating what
    the docstring of a very simple function looks like.

    Parameters
    ----------
    num1 : int
        First number to add.
    num2 : int
        Second number to add.

    Returns
    -------
    int
        The sum of ``num1`` and ``num2``.

    Raises
    ======
     MyException
        if anything bad happens

    See Also
    --------
    subtract : Subtract one integer from another.

    Examples
    --------
    >>> add(2, 2)
    4
    >>> add(25, 0)
    25
    >>> add(10, -10)
    0
    """
    return num1 + num2

3.Sphinx 文档字符串

没有什么比旧的 sphinx 文档字符串更好的了，这是使用的最基本的文档字符串格式，但在视觉上有些密集，因此难以阅读。 相同的格式是：

def sphinx_docstrings(num1, num2) -> int:
    """Add up two integer numbers.

    This function simply wraps the ``+`` operator, and does not
    do anything interesting, except for illustrating what
    the docstring of a very simple function looks like.

    :param int num1: First number to add.
    :param int num2: Second number to add.
    :returns:  The sum of ``num1`` and ``num2``.
    :rtype: int
    :raises AnyError: If anything bad happens.
    """
    return num1 + num2

结论

除了上述格式之外，还有许多可用于 Python 的 docstring 格式，我们在这场比赛中没有一个赢家。

所以选择你喜欢的格式，不要混合格式，并在整个项目中坚持下去。 我个人最喜欢的是 NumPy 的 Docstring！