Python PEP-8 return value formatting

Question

I'm not sure I've seen a specific answer to this, but I have a question regarding the style conventions on return values for my python docstrings.

Consider a function like:

def foo(ex):
    output = 2*ex
    return output

In PyCharm, if I made a docstring for this function, it would look like:

def foo(ex):
    """
    Sample text....
    :param ex: description...
    :return: description of return value
    """
    output = 2*ex
    return output

My question is whether or not I should name my return value in the docstring? i.e.

:return: description of return value

:return: output: description of return value

Is there a coding standard for this or is it mostly left to personal preference?

Answer 1

As already mentioned by randomir, the Python PEPs do not specify how the content of docstrings should be structured. However big coding projects usually have their own guidelines for docstring content, and you could adapt one of those.

Personally I like the Numpy docstring format (see here and here). The local name of a return value is not included in Numpy-style docstrings. The docstring for your function would look like this:

def foo(ex):
    """One-line function description.

    Parameters
    ----------
    ex : float
        Description of parameter.

    Returns
    -------
    float
        Description of return value.

    """
    output = 2*ex
    return output

Numpy-style docstrings are supported by Sphinx documentation generator as well.