35

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 that is returns two arguments. I don't think napoleon handles this. If so, could someone tell me how they handle it?

def foo(a):
'''one line summary

longer explanation

Args:
  a (int): parameter description

Returns:
  servers (list): list of servers to use
  msg (str): logging message string 
'''
pass

Maybe I'm getting a message that it is not great coding style to return multiple arguments, but can you do this? The html generated treats those two lines as part of a description for one argument. If I put a newline between the servers and msg line, it helps, but it is still documenting one arg.

1

4 Answers 4

38

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

6
  • 1
    I am not sure if that's what the OP is referring to, but what if you have a function like if foo: return foo else: return bar?
    – Railslide
    Mar 30, 2015 at 10:38
  • yeah its ambiguous. the OP should post some code to make it clear
    – mor22
    Mar 30, 2015 at 13:52
  • 1
    You might need an extra line in between; I've updated the example above. I'm not using the google style. I know that the Numpy Style does support multiple return values. Checkout sphinxcontrib-napoleon.readthedocs.org/en/latest/…
    – mor22
    Mar 31, 2015 at 8:48
  • 2
    Looks like Google style won't support multiple return values: bitbucket.org/birkenfeld/sphinx-contrib/issues/111/… Sep 12, 2015 at 11:54
  • 1
    @MrCartoonology I use a dash before each of the tuple elements to turn them into a bullet-pointed list. In the ReadTheDocs style I'm using, they now look similar to the arguments.
    – AstroFloyd
    Oct 18, 2019 at 16:33
20

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.

2
5

You can configure napoleon to interpret the Returns section of a Google-style docstring like the Args section using the napoleon_custom_sections setting.

napoleon_custom_sections = [('Returns', 'params_style')]

This way, multiple return values (as given in the question) are rendered nicely by Sphinx. However, I am not entirely sure if one is still strictly adhering to the Google-style docstring convention when using this option.

0

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.