web-dev-qa-db-ja.com

python docstringのパラメータ説明の複数行の説明

したがって、reStructuredTextは 推奨される方法 Pythonコードのドキュメントです。十分に努力すれば、次のことができます sphinxのドキュメントで検索 方法関数のシグネチャドキュメントを正規化します。例はすべて1行ですが、パラメータの説明が次のように複数行の場合はどうなりますか？

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レンダリングを壊しますか？

pythoncoding-stylepython-sphinxrestructuredtextdocstring
31
Jocelyn delalande

：param：ディレクティブに対して少なくとも1レベルインデントした場合、reSTructuredTextレンダリングが中断されないようです。個人的には、すべての追加行をそのパラメーターの最初の説明行に揃えることを好みます。 reSTは改行も無視し、改行なしでテキストをレンダリングすることに注意してください。

残念ながら、この問題について言及したり、複数行の：param：記述の例を提供したりするソースは見つかりませんでした。

17
Julia Niewiejska

改行して改行します。

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

元のポスターからのよい研究努力。 正規のスフィンクスのドキュメントがparams の複数行の例を示していないのは驚きですが、複数行のドキュメントは PEP8 の79文字のガイドライン。

実際には、パラメータ名自体は通常Wordまたはさらに長いsnake_case_words、すでに長い<4 or 8+ spaces> :param、次の行のインデントを1レベルだけ（つまり、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はこれらのdocstringを取得して docs を問題なく生成できます。

7
RayLuo

署名のレンダリングは docutilsフィールドリスト に基づいています。リンクには、インデントする方法の例が含まれています。たとえば、アイテムの説明をアイテム化または列挙したリストにする場合などです。

0
user4184837

はい、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
    """
0
Lenka42