Descripción de varias líneas de una descripción de parámetro en python docstring

Entonces, reStructuredText es
la forma recomendada para la documentación del código de Python, si se esfuerza lo suficiente, puede
encontrar en la documentación de la esfinge
cómo normalizar la documentación de la firma de su función. Todos los ejemplos dados son de una sola línea, pero ¿qué pasa si la descripción de un parámetro es de varias líneas como la siguiente?

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

¿Cuál es la sintaxis/convención para eso? ¿Debo sangrar o no? ¿Romperá la representación de reStructuredText?

Buen esfuerzo de investigación del cartel original. Es una sorpresa que el
La documentación de la esfinge canónica no proporciona un ejemplo de varias líneas en los parámetros.a pesar de que el documento de varias líneas es inevitable debido a la
Pauta de 79 caracteres en PEP8.

En la práctica, teniendo en cuenta que el nombre de su parámetro en sí mismo suele ser un word o incluso más snake_case_wordsprecedido por el ya largo <4 or 8+ spaces> :paramsería prudente hacer la sangría de la siguiente línea solo para un nivel (es decir, 4 espacios), que coincida con el estilo de “sangría francesa” mencionado en
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.
        """

PD: Puedes verlo en acción en, por ejemplo,
aquí. Sphinx puede recoger esos docstrings y genera
documentos sin ningún problema

Parece que si aplica una sangría de al menos un nivel en relación con la directiva :param: , no interrumpirá la representación de reSTructuredText. Personalmente, prefiero alinear todas las líneas adicionales con la primera línea de descripción de ese parámetro. Tenga en cuenta que reST también ignorará las líneas nuevas y representará su texto sin saltos de línea.

Desafortunadamente, no pude encontrar ninguna fuente que mencionara este problema o diera un ejemplo de una descripción de :param: de varias líneas.

simplemente nueva línea donde desea que se rompa la línea.

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

Sí, parece que cualquier sangrado cómodo para usted funciona para Sphinx y pep8 no discute. Además, si no desea que la descripción sea de varias líneas en la documentación producida, puede usar los saltos de línea tradicionales de Python con \:

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

La representación de firmas se basa en listas de campos de docutils. El enlace contiene ejemplos de cómo sangrar, por ejemplo, si desea que la descripción de su artículo sea una lista detallada o enumerada.

Mira aquí:

:Date: 2001-08-16
:Version: 1
:Authors: - Me
          - Myself
          - I
:Indentation: Since the field marker may be quite long, the second
   and subsequent lines of the field body do not have to line up
   with the first line, but they must be indented relative to the
   field name marker, and they must line up with each other.
:Parameter i: integer