I document all my Python functions with reStructuredText doc strings. Unfortunately, I am missing a way to describe multiple return values. All standard references I found only refer to the case of one return value, such as Sphinx-Doc or Realpython.
Example:
def get_linear_function_2d(p1, p2):
"""
Compute 2d linear function in slope-intercept form
y = mx + n
based on two coinciding (x,y) points.
:param tuple p1: (x,y) tuple describing one point that lies on the line
:param tuple p2: (x,y) tuple describing another point that lies on the line (has to differ in x)
<START OF ISSUE: How to document?>
:return float: slope (m)
:return float: y-intercept (n)
<END OF ISSUE>
"""
assert isinstance(p1, tuple) and len(p1) == 2 and all([isinstance(val, (int, float)) for val in p1])
assert isinstance(p2, tuple) and len(p2) == 2 and all([isinstance(val, (int, float)) for val in p2])
assert p1[0] != p2[0]
m = (p2[1] - p1[1]) / (p2[0] - p1[0])
n = p1[1] - m * p1[0]
return m, n
Remark: This question has been raised for Python 2, see How to document multiple return values using reStructuredText in Python 2?.
However:
- that question had been dedicated to Python 2
- some years have passed
- the answers do not link any official reference
- even if there is no official reference for multiple return values, it is not clear to me what is best practice (none of the two answers stands out) - I think it is a pretty common issue and I am eager to see how you guys work around this lack of standard!
