Multi-line description of a parameter description in python docstring

Question

So, reStructuredText is the recommended way for Python code documentation, if you try hard enough, you can find in the sphinx documentation how to normalize your function signature documentation. All given examples are single-line, but what if a parameter description is multi-line like the following ?

def f(a, b):
    """ Does something with a and b

    :param a: something simple
    :param b: well, it's not something simple, so it may require more than eighty
              chars
    """

What is the syntax/convention for that ? Should I indent or not ? will it break reSTructuredText rendering ?

Answer 1

Seems that if you indent by at least one level relative to the :param: directive, it will not break reSTructuredText rendering. Personally, I prefer to align all additional lines to the first description line of that parameter. Note, that reST will also ignore new lines and render your text without your line breaks.

Unfortunately, I could not find any source that would mention this issue or give an example of a multi-line :param: description.