Description
When using NumPy-style docstrings, I can document multiple return values. Let us consider the following function as an example (version 1):
def foo(a, b):
"""Function
Parameters
----------
a : float
First number
b : float
Second number
Returns
-------
result_sum : float
Sum of numbers
result_prod : float
Product of numbers
"""
result_sum = a + b
result_prod = a * b
return result_sum, result_prodWhen using autodoc, napoleon, and the rtd theme, the API documentation is rendered as follows:
I would like to obtain the same result using Google-style docstrings. The Google-style version of the docstring looks as follows (version 2):
def foo(a, b):
"""Function
Args:
a (float): First number
b (float): Second number
Returns:
result_sum (float): Sum of numbers
result_prod (float): Product of numbers
"""
result_sum = a + b
result_prod = a * b
return result_sum, result_prodHowever, the rendering of this docstring is messed up. It does not seem to be recognized that there are two return values instead of a single one.
There are two related StackOverflow questions ([1], [2]), where some users recommend using a docstring in the following style (version 3):
def foo(a, b):
"""Function
Args:
a (float): First number
b (float): Second number
Returns:
tuple containing
- result_sum (float): Sum of numbers
- result_prod (float): Product of numbers
"""
result_sum = a + b
result_prod = a * b
return result_sum, result_prodThis docstring is rendered as follows:
However, I feel that there is a semantic difference between version 1 and version 3. Version 1 documents that there are two return values. Version 3 documents that there is a single return value (a tuple). Although both perspectives are the same from a technical point of view, the versions have different flavors. Furthermore, the formatting is missing in version 3 (bold return value name, italic return value type).
I would like to obtain the same output as in version 1, using clean Google-style docstrings (without messing around too much with the docstring, e.g., **bold** formatting in the docstring). I am not sure if the output of version 2 is a bug or if it is intended to be like this.
I use sphinx 4.0.0b1.dev20210414 and sphinx-rtd-theme 0.5.2. Note that the problem also exists when using in-package themes, such as classic or alabasta. (I.e., it is not related to sphinx-rtd-theme).
Many thanks for any help on this issue.