How to document multiple return values using reStructuredText in Python 2?

Question

The Python docs say that "the markup used for the Python documentation is reStructuredText". My question is: How is a block comment supposed to be written to show multiple return values?

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

I've found a tutorial on Python documentation using reStructuredText, but it doesn't have an example for documenting multiple return values. The Sphinx docs on domains talks about returns and rtype but doesn't talk about multiple return values.

Answer 1

There is a compromised solution: just write in normal Markdown texts. e.g.

def func(a, b):
    """

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

    return x, y

This will generate the following document:

Almost what we want, right?

The shortcoming for this is that you cannot specify return type for every element. You would have to write it by yourself, such as

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