如何在Python2中使用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?
    """

我找到了一个使用reStructuredText的tutorial on Python文档，但它没有记录多个返回值的示例。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在评论中提到的那样，所使用的详细格式并没有严格定义。

就我自己而言，我通常使用上面使用的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 ....        
    """