つまり、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 のレンダリングが壊れますか?
ベストアンサー1
オリジナルポスターの調査努力は素晴らしい。標準的な Sphinx ドキュメントでは、パラメータに関する複数行の例は示されていません。複数行の文書は、PEP8の79文字のガイドライン。
実際には、パラメータ名自体が通常wordまたはそれよりも長くsnake_case_words、すでに長い が先頭に付いていることを考慮すると<4 or 8+ spaces> :param、次の行のインデントを 1 レベル (つまり 4 スペース) だけ行うことが賢明です。これは、で説明した「ぶら下げインデント」スタイルと一致します。ペップ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はこれらのdocstringsを拾い上げて生成しますドキュメント問題なく。