it-swarm.com.de

Mehrzeilige Beschreibung einer Parameterbeschreibung in Python-Docstring

ReStructuredText ist also der empfohlene Weg für die Dokumentation zum Python-Code . Wenn Sie sich bemühen, können Sie in der Sphinx-Dokumentation finden wie Sie die Dokumentation Ihrer Funktionssignatur normalisieren. Alle angegebenen Beispiele sind Einzeilig, aber was ist, wenn eine Parameterbeschreibung mehrzeilig ist wie die folgende ?

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

Was ist die Syntax/Konvention dafür? Soll ich einrücken oder nicht? wird das reSTructuredText-Rendering brechen?

21

Es scheint, dass, wenn Sie um mindestens eine Ebene relativ zur: param: -Direktive eingerückt werden, die Wiedergabe von reSTructuredText nicht unterbrochen wird. Ich persönlich bevorzuge es, alle zusätzlichen Zeilen an der ersten Beschreibungszeile dieses Parameters auszurichten. Beachten Sie, dass reST auch neue Zeilen ignoriert und Ihren Text ohne Zeilenumbrüche rendert.

Leider konnte ich keine Quelle finden, die dieses Problem erwähnte, oder ein Beispiel für eine mehrzeilige: param: description.

13

einfach Zeilenumbruch, wo die Linie unterbrochen werden soll.

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

Gute Recherche vom Originalposter. Es ist überraschend, dass die kanonische Sphinxdokumentation kein mehrzeiliges Beispiel für Parameter gibt, obwohl das mehrzeilige Dokument aufgrund des 79 unvermeidlich ist -Zeichenrichtlinie in PEP8 .

Wenn Sie berücksichtigen, dass Ihr Parametername normalerweise Word oder sogar noch länger snake_case_words ist und der bereits Länge <4 or 8+ spaces> :param vorangestellt ist, ist es in der Praxis ratsam, die nächste Zeile für nur eine Ebene (dh 4 Leerzeichen) einzurücken, die dem "hängenden" entspricht Einrückungen "Stil in 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: Sie können es in Aktion zum Beispiel in hier . Sehen. Sphinx kann diese Docstrings aufheben und docs ohne Probleme erzeugen .

3
RayLuo

Ja, es scheint, als ob für Sie eine bequeme Eindrückung für Sphinx funktioniert, und pep8 argumentiert nicht. Wenn Sie nicht möchten, dass die Beschreibung in der erstellten Dokumentation mehrzeilig ist, können Sie traditionelle Python-Zeilenumbrüche mit \ verwenden:

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

Das Rendern von Signaturen basiert auf docutils Feldlisten . Der Link enthält Beispiele für das Einrücken, z. B. wenn Ihre Artikelbeschreibung eine Einzelteil- oder Aufzählungsliste sein soll.

0
user4184837