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。我找到了一些选择，特别是看着狮身人面像。它似乎做了我想要的（虽然我努力使它生成一个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甚至有一个用于推理和类型检查的类型提示系统，它首先检查docstring中的声明。

这是一个可以用来自动进行转换的正则表达式。取代

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

与

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

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

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

2 个答案: