如何在 Python 2 中使用 reStructuredText 记录多个返回值？

Question

在Python文档说，“用于Python文档的标记是reStructuredText的”。我的问题是：应该如何编写块注释以显示多个返回值？

def func_returning_one_value():
    """Return just one value.

    :returns: some value
    :rtype: str
    """

def func_returning_three_values():
    """Return three values.

    How do I note in reStructuredText that three values are returned?
    """

我找到了使用 reStructuredText 的 Python 文档教程，但它没有用于记录多个返回值的示例。在上域狮身人面像文档有关的会谈returns和rtype，但不会谈论多个返回值。

Answer 1

正如 wwi 在评论中提到的，要使用的详细格式没有严格定义。

对于我自己，我通常使用您上面使用的字段列表符号样式。它支持换行，所以在你觉得有必要的地方换行

def my_func(param1, param2):
    """
    This is a sample function docstring

    :param param1: this is a first param
    :param param2: this is a second param
    :returns: tuple (result1, result2) 
        WHERE
        str result1 is .... 
        str result2 is ....        
    """

Answer 2

有一个折衷的解决方案：只用普通的 Markdown 文本编写。例如

def func(a, b):
    """

    :param int a: first input
    :param int a: second input
    :returns: 
        - x - first output
        - y - second output
    """

    return x, y

这将生成以下文档：

几乎是我们想要的，对吧？

这样做的缺点是您不能为每个元素指定返回类型。您必须自己编写它，例如

"""
:returns:
    -x (:py:class:`int`) - first output
"""