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

Question

Python docs说“用于 Python 文档的标记是 reStructuredText”。我的问题是:应该如何编写 block 注释来显示多个返回值？

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

我找到了 tutorial在使用 reStructuredText 的 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
"""