最常见的Python文档字符串格式是什么？[已关闭]格式转换/生成

coding-style python documentation docstring

2022-09-05 01:04:54

我在Python中看到了几种不同风格的文档字符串，最流行的风格是什么？

答案 1

格式

Python文档字符串可以按照其他帖子所示的几种格式编写。然而，没有提到默认的Sphinx文档字符串格式，它基于reStructuredText（reST）。您可以在此博客文章中获得有关主要格式的一些信息。

请注意，PEP 287 建议使用 reST

以下是文档字符串的主要使用格式。

- Epytext

从历史上看，类似javadoc的风格很普遍，因此它被用作Epydoc（使用称为格式）生成文档的基础。Epytext

例：

"""
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
"""

- 雷斯特

如今，可能更流行的格式是Sphinx用来生成文档的reStructuredText（reST）格式。注意：默认情况下，它在 JetBrains PyCharm 中使用（在定义方法后键入三重引号并按 Enter 键）。默认情况下，它也被用作Pyment中的输出格式。

例：

"""
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
"""

- 谷歌

谷歌有自己经常使用的格式。它也可以通过Sphinx解释（即使用拿破仑插件）。

例：

"""
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.
"""

更多示例

- 努姆皮多克

请注意，Numpy建议遵循他们自己的基于Google格式的numpydoc，并可供Sphinx使用。

"""
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
"""

转换/生成

可以使用像Pyment这样的工具自动生成尚未记录的Python项目的文档字符串，或者将现有的文档字符串（可以混合多种格式）从一种格式转换为另一种格式。

注意：这些示例取自 Pyment 文档

答案 2

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