从用 PEP8 编写的 Python 文档字符串制作 API

Question

我已经在 Python 中编写了代码。我试图遵循有关在函数开头编写有用注释的通用准则。我的风格是 PEP8，例如

def __init__(self, f_name=None, list_=None, cut_list=None, n_events=None, description=None):
        """
        Parse an LHCO or ROOT file into a list of Event objects.

        It is possible to initialize an Events class without a LHCO file,
        and later append events to the list.

        Arguments:
        f_name -- Name of an LHCO or ROOT file, including path
        list_ -- A list for initalizing Events
        cut_list -- Cuts applied to events and their acceptance
        n_events -- Number of events to read from LHCO file
        description -- Information about events
        """

我想从我的代码中自动生成有用的 API。我找到了几个选项，特别关注 Sphinx。它似乎做了我想要的（尽管我努力让它生成 API，而不是我的程序手册）。然而，缺点是它有自己的文档字符串预期样式：

"""
:param x: My parameter
:type x: Its type
"""

用这种语法重写我所有的文档字符串对我来说真的最好吗？他们产生了一个不错的 API，但我不喜欢在代码中使用它们，如果结果证明这是一个坏主意，那将非常耗时。什么是标准、最佳实践？我应该转换吗？如果是这样，有什么可以自动为我做的吗？

Answer 1

文档字符串的 Sphinx 默认格式确实非常强大，如果您想生成干净的 API 文档并且如果您需要在数月、数年内审查自己的代码，那么绝对值得花时间。所以是的，这是个好主意。

如果您不喜欢默认的 Sphinx-ReST 语法，您可以尝试编写文档字符串 the way Numpy do，例如：

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

    """
    return True

有一个 Sphinx 扩展 (Napoleon) 允许 Sphinx 解析此样式（或 Google 样式，后者更简单）。

Answer 2

我认为 Sphinx 语法非常轻量级（很高兴它不是 Javadoc），所以就非常原始的代码而言，这并不是一个严重的缺点。

我的 IDE、PyCharm 在我向函数添加文档字符串时自动创建 Sphinx 样式的骨架。所以有些开发人员对 Python 略知一二（他们也很喜欢在其他领域推动 PEP8 风格）并推荐 Sphinx。 PyCharm 甚至有一个用于推理和类型检查的类型提示系统，它首先检查文档字符串中的声明。

这是一个可用于自动进行转换的正则表达式。替换

^(\s+)(\w+) -- (.+)$

与

:param : \n:type :

其中$n代表第n组。当然你需要自己填写类型

从用 PEP8 编写的 Python 文档字符串制作 API

Making API from Python docstrings written in PEP8

python

docstring

python-sphinx