Multi-line-Beschreibung der parameter Beschreibung in python docstring

So, reStructuredText ist
der empfohlene Weg für Python-code
Dokumentation, wenn Sie hart genug versuchen, Sie können
finden Sie in der sphinx-Dokumentation
wie zu normalisieren Ihre Funktion Unterschrift-Dokumentation. Alle angegebenen Beispiele sind
single-line, aber was ist, wenn ein parameter Beschreibung multi-Zeile 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 für das ? Sollte ich Einrücken oder nicht ? wird es brechen, reSTructuredText-rendering ?

InformationsquelleAutor Jocelyn delalande | 2015-09-14
  1. 18

    Scheint, dass, wenn Sie Einrücken von zumindest einer Ebene relativ zu dem :param: Richtlinie, es wird nicht brechen, reSTructuredText-rendering. Persönlich, ich bevorzugen, richten Sie alle zusätzlichen Zeilen, um die erste Zeile Beschreibung der parameter.
    Beachten Sie, dass der reST auch ignorieren, neue Linien und machen Ihren text ohne Ihre Zeilenumbrüche.

    Leider konnte ich nicht finden, eine Quelle wäre zu erwähnen, dass dieses Problem oder geben Sie ein Beispiel einer multi-line :param: Beschreibung.

    InformationsquelleAutor Julia Niewiejska
  2. 9

    einfach newline, wo Sie wollen die Linie zu brechen.

    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
    """
    • meine Frage ist mehr: wie Gedankenstrich oder nicht (ich Bearbeiten, um deutlich zu machen)
    InformationsquelleAutor Amazingred
  3. 7

    Gute Forschung aus der Original-Poster. Ist es eine überraschung, dass die
    canonical-sphinx Dokumentation nicht mit einer multi-line-Beispiel params, trotz der Tatsache, dass multi-line-Dokument ist unvermeidlich, aufgrund der
    79-Charakter-Richtlinie in PEP8.

    In der Praxis, wenn man bedenkt, dass Ihre parameter name selbst ist in der Regel eine word oder sogar mehr snake_case_words, vorangestellt, die bereits mehrere <4 or 8+ spaces> :param ist, wäre es klug, um die nächste Zeile Einrücken, für die nur eine Stufe (also 4 Räume), was mit der "hängende Einzüge" style metioned 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 ihn in Aktion zu sehen, zum Beispiel,
    hier.
    Sphinx abholen können diejenigen, docstrings und erzeugt
    docs ohne Problem.

    InformationsquelleAutor RayLuo
  4. 1

    Ja, scheint, wie jede bequeme für Sie die Einrückung funktioniert für Sphinx und pep8 nicht argumentieren. Auch, wenn Sie nicht wollen, eine Beschreibung multiline-in produzierten Dokumentation können Sie verwenden, Python-traditionelle Linie breakes mit \:

     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
    """
    InformationsquelleAutor Lenka42
  5. 0

    Signaturen rendering basiert auf docutils Feld Listen. Der link enthält Beispiele zum Einzug, zum Beispiel, wenn Sie möchten, Ihr Einzelteil Beschreibung, um eine in Elemente untergliederte oder Aufzählung.

    InformationsquelleAutor
Schreibe einen Kommentar