web-dev-qa-db-fra.com

Description multiligne d'une description de paramètre dans python docstring

Ainsi, reStructuredText est la méthode recommandée pour la documentation du code Python . Si vous essayez suffisamment, vous pouvez trouver dans la documentation sphinx comment normaliser la documentation de votre signature de fonction. Tous les exemples donnés sont Sur une seule ligne, mais que se passe-t-il si la description d'un paramètre est multiligne comme le Suivant?

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

Quelle est la syntaxe/convention pour cela? Dois-je mettre en retrait ou non? va-t-il interrompre le rendu reSTructuredText?

pythoncoding-stylepython-sphinxrestructuredtextdocstring
21
Jocelyn delalande

Il semble que si vous indenter au moins un niveau par rapport à la directive: param:, le rendu reSTructuredText ne sera pas interrompu. Personnellement, je préfère aligner toutes les lignes supplémentaires sur la première ligne de description de ce paramètre. Notez que reST ignorera également les nouvelles lignes et rendra votre texte sans vos sauts de ligne.

Malheureusement, je n'ai trouvé aucune source qui mentionne ce problème ou donne un exemple de multi-ligne: param: description.

13
Julia Niewiejska

simplement newline où vous voulez que la ligne se casse.

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

Bon effort de recherche de l'affiche originale. Il est surprenant que la documentation canonical sphinx ne donne pas un exemple multiligne sur params , alors que le document multiligne est inévitable en raison de la recommandation de 79 caractères dans PEP8 .

En pratique, étant donné que votre nom de paramètre lui-même est généralement un Word ou même un snake_case_words plus long, préfixé par le <4 or 8+ spaces> :param déjà long, il serait sage de faire en sorte que la ligne suivante soit indentée pour un seul niveau (c'est-à-dire 4 espaces), "indents" dans le style 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: Vous pouvez le voir en action dans, par exemple, ici . Sphinx peut récupérer ces docstrings et générer docs sans aucun problème.

3
RayLuo

Oui, il semblerait que tout ce qui est confortable pour vous d’indenter fonctionne pour Sphinx et pep8 ne discute pas. De plus, si vous ne voulez pas que la description soit multiligne dans la documentation produite, vous pouvez utiliser les sauts de ligne traditionnels Python avec \:

 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

Le rendu des signatures est basé sur les listes de champs docutils . Le lien contient des exemples de mise en retrait, par exemple si vous souhaitez que la description de votre article soit une liste énumérée ou énumérée.

0
user4184837