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

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

Answer 2

As wwi mentioned in the comments, the detailed format to be used is not strictly defined.

For myself, I usually use the Field List notation style you use above. It supports line breaks, so just break where you feel is necessary

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