Multi-line description of a parameter description in python docstring
Solution 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.
Solution 2
Good research effort from the Original Poster. It is a surprise that the canonical sphinx documentation does not give a multi-line example on params, despite the fact that multi-line document is inevitable due to the 79-character guideline in PEP8.
In practice, considering that your parameter name itself is typically a word
or even longer snake_case_words
, prefixed by the already lenghty <4 or 8+ spaces> :param
, it would be wise to make the next line indent for just one level (i.e. 4 spaces), which matches the "hanging indents" style metioned in
PEP 8.
class Foo(object):
def f(a, bionic_beaver, cosmic_cuttlefish):
""" Does something.
:param a: something simple
:param bionic_beaver: well, it's not something simple,
so it may require more than eighty chars,
and more, and more
:param cosmic_cuttlefish:
Or you can just put all your multi-line sentences
to start with SAME indentation.
"""
PS: You can see it in action in, for example, here. Sphinx can pick up those docstrings and generates docs without any issue.
Solution 3
simply newline where you want the line to break.
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
"""
Solution 4
Yes, seems like any comfortable for you indentation works for Sphinx and pep8 doesn't argue. Also, if you don't want description to be multiline in produced documentation you may use Python traditional line breakes with \
:
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
"""
Solution 5
Signatures rendering is based upon docutils field lists. The link contains examples of how to indent, for example if you want your item description to be an itemized or enumerated list.
See here:
:Date: 2001-08-16
:Version: 1
:Authors: - Me
- Myself
- I
:Indentation: Since the field marker may be quite long, the second
and subsequent lines of the field body do not have to line up
with the first line, but they must be indented relative to the
field name marker, and they must line up with each other.
:Parameter i: integer
Related videos on Youtube
Jocelyn delalande
Jocelyn Delalande (homepage) FAIMaison : Non-profit DIY ISP Some code/tools for Rhizome github personal projects repository
Updated on July 08, 2022Comments
-
Jocelyn delalande almost 2 years
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 ?
-
Jocelyn delalande almost 9 yearsmy question is more about how to indent or not (I edit to make it clear)
-
CodePrinz about 3 yearsJust make sure, there is the empty line above the first
:param ...
. Otherwise it will look like there is an indentation error, but the problem will be the line! -
RayLuo about 3 years@CodePrinz, true. And that is actually the usual docstring requirement, even when you are not documenting each parameter. Basically, the first paragraph of a docstring is considered as a summary, and it should ideally be as short as a one-liner. And then a blank line ends the first paragraph. All the subsequent paragraphs, if any, become the details of your doc. Therefore, all those parameters content should go into the 2nd or later paragraph.