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

Question

因此,reStructuredText是 Python代码文档的推荐方法,如果你足够努力,你可以 在sphinx文档中找到 如何规范化你的函数签名文档.所有给出的示例都是单行的,但是如果参数描述是多行的,如下所示呢？

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

似乎如果你相对于:param:指令至少缩进一个级别,它将不会破坏reSTructuredText呈现.就个人而言,我更喜欢将所有其他行对齐到该参数的第一个描述行.请注意,reST还会忽略换行并在没有换行的情况下渲染文本.

不幸的是,我找不到任何提及此问题的来源或提供多行示例:param:description.

Answer 2

只需要换行,你想要换行.

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

Answer 3

来自原始海报的良好研究工作。令人惊讶的是 ，尽管由于PEP8中的79个字符的准则，多行文档是不可避免的，但是 规范化的狮身人面像文档并未提供关于params的多行示例。

实际上，考虑到您的参数名称本身通常是a 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.
        """

PS：您可以在 这里查看实际运行情况。Sphinx可以拾取这些文档字符串并生成 文档，而不会出现任何问题。

Answer 4

是的，似乎任何让你舒服的缩进都适用于 Sphinx，并且 pep8 不会争论。另外，如果您不希望生成的文档中的描述为多行，您可以使用 Python 传统换行符\：

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