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

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

Answer 1

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

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