python docstring中参数描述的多行描述

Question

所以，structuredText是 the recommended way对于Python代码 文档，如果你足够努力，你可以 find in the sphinx documentation 如何规范化函数签名文档。所有的例子都是 单行，但是如果参数描述是多行的，如下面所示 ?

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
    """

它的语法/惯例是什么？我应该缩进还是不缩进？是否会中断reSTructuredText呈现？

Answer 1

原版海报的良好研究成果。令人惊讶的是 canonical sphinx documentation does not give a multi-line example on params，尽管由于 79-character guideline in PEP8。

实际上，考虑到参数名本身通常是一个word或更长的snake_case_words，前缀是已经很长的<4 or 8+ spaces> :param，明智的做法是使下一行只缩进一个级别（即4个空格），这与中所述的“挂起缩进”样式相匹配 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.
        """

注：例如，你可以在， here。 Sphinx可以获取这些docstring并生成 docs没有任何问题。

Answer 2

似乎如果相对于：param:指令缩进至少一个级别，它不会中断reSTructuredText呈现。就我个人而言，我更喜欢将所有附加行与该参数的第一个描述行对齐。 注意，reST还将忽略新行，并在不换行的情况下呈现文本。

不幸的是，我找不到任何提到这个问题的来源，也找不到多行的示例：param:description。

Answer 3

只需换行就可以了。

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
    """