Can Sphinx napoleon document function returning multiple arguments?
Solution 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
Solution 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.
Solution 3
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.
![MrCartoonology](https://i.stack.imgur.com/BdYnJ.jpg?s=256&g=1)
MrCartoonology
I am a software engineer/mathematician. Work involves contributing to a software framework written in C++ and Python for scientists to do data analysis - mostly using the Python data analysis stack. Projects involve machine learning, MPI and parallel programming, C++ architecture, and HDF5 programming. One of my hobbies is cartooning, see: jordysjungle.com where I dabble with django.
Updated on June 03, 2022Comments
-
MrCartoonology about 2 years
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.
-
Railslide about 9 yearsI 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
? -
mor22 about 9 yearsyeah its ambiguous. the OP should post some code to make it clear
-
MrCartoonology about 9 yearsThanks! That is what I'm looking for, and it makes sense, it is probably good to document the return type as tuple rather than jumping right into a description of the tuple elements like I thought I could, but I couldn't quite get it to work (I have very little experience with sphinx at present). The two lines that describe servers and msg do start on a newly indented line, but there is no parsing of the lines, they are treated as one paragraph. Can I get sphinx/napoleon to introduce the same kind of formatting it applies to Args parameters to the tuple elements?
-
mor22 about 9 yearsYou 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/…
-
Ilya Etingof almost 9 yearsLooks like Google style won't support multiple return values: bitbucket.org/birkenfeld/sphinx-contrib/issues/111/…
-
Sibbs Gambling about 5 yearsDo you think aliasing Returns to Args is a better idea for this purpose? sphinxcontrib-napoleon.readthedocs.io/en/latest/…
-
moi almost 5 years@SibbsGambling No, because then the extra values would be merged into the existing Parameters.
-
AstroFloyd over 4 years@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.