从用PEP8编写的Python文档字符串生成API

我已经用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。我找到了一些选择，特别是斯芬克斯。它似乎做了我想做的事情（尽管我很难让它生成API，而不是我的程序手册）。然而，缺点是它有自己预期的docstring样式：

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

---

用这种语法重写我所有的docstring对我来说真的是最好的吗？它们产生了一个很好的API，但我不喜欢代码中的API，如果结果证明这是一个坏主意，那将很耗时。什么是标准、最佳实践？我应该皈依吗？如果是这样的话，有什么东西可以为我自动完成吗？

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

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

---

有一个Sphinx扩展（）允许Sphinx解析这种样式（或者更简单的Google样式）。

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

我的IDE PyCharm在向函数添加docstring时自动以Sphinx样式创建骨架。因此，有些开发人员对Python略知一二（也喜欢在其他领域大力推广PEP8风格），并推荐Sphinx。PyCharm甚至有一个用于推理和类型检查的类型提示系统，它从检查docstring中的声明开始

这里有一个正则表达式，可以用来自动进行转换。替换

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

与

其中，

$n

表示第n组。当然，您需要自己填写类型

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

$1:param $2: $3\n$1:type $2: