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

Question

Python docs 表示“用于 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?
    """

我在 Python 文档中使用 reStructuredText 找到了tutorial，但它没有记录多个返回值的示例。 Sphinx docs on domains 讨论了 returns 和 rtype，但没有讨论多个返回值。

Answer 1

有一个折中的解决方案：只写普通的 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
"""

Answer 2

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

就我自己而言，我通常使用您在上面使用的Field List 表示法样式。它支持换行，所以只要在你认为有必要的地方换行就行了

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