Question

所以，reStructuredText是 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

似乎如果相对于：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

原创海报的精彩研究工作。令人惊讶的是 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.
        """

PS：你可以看到它在行动中，例如， here。 Sphinx可以获取这些文档字符串并生成 docs没有任何问题。

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

Answer 5

签名呈现基于docutils field lists。该链接包含如何缩进的示例，例如，如果您希望项目描述为逐项列表或枚举列表。

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

5 个答案: