Can Sphinx napoleon document function returning multiple arguments?

Question

I am trying to use the Google code style to document a function that I then use sphinx with the napoleon extension to create documentation for. The function is unusual in th

Answer 1

Python only returns a single object. If you call

serv,msg = foo(myinput)

Then you are explicitly expanding the expression_list tuple which is generated when the function returns with this code

return servers,msg

You docstring should read some thing like this (with the Napoleon Google Style)

"""
one line summary

longer explanation

Args:
    a (int): parameter description

Returns:
    (tuple): tuple containing:

        servers(list) servers to use
        msg (str): logging message string 
"""

Or with the Napoleon NumPy style:

"""
one line summary

longer explanation

Parameters
----------
a : int
    parameter description

Returns
-------
servers : list
    servers to use
msg : str
    logging message string 
"""

Have a look at the python docs for return and perhaps expression_list

Answer 2

Google style does not support multiple return values. As a workaround you can use:

Returns:
        2-element tuple containing

        - **rates** (*array*): the unnormalized rates (just the sum of the
          exponential kernels). To obtain rates in Hz divide the
          array by `2*tau` (or other conventional `x*tau` duration).
        - **nph** (*array*): number of photons in -5*tau..5*tau window
          for each timestamp. Proportional to the rate computed
          with KDE and rectangular kernel.

This results in a nice output even with multi-line description for each returned item.

Answer 3

After trying several options, this format worked for me

def foo(a):
    """
    
    Args:
        a (int): parameter description

    Returns:
        - list: 
          parameter description
        - str: 
          logging message string
    """

Note the two spaces after the linebreak.