comandos - python documentation español

Descripción multilínea de la descripción de un parámetro en la cadena de documentación de Python

Question

Por lo tanto, reStructuredText es la forma recomendada para la documentación del código Python. Si se esfuerza lo suficiente, puede encontrar en la documentación de sphinx cómo normalizar la documentación de la firma de funciones. Todos los ejemplos dados son de una sola línea, pero ¿qué sucede si la descripción de un parámetro es multilínea 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á el renderizado de texto estructurado?

Answer 1

Buen esfuerzo de investigación del Póster Original. Es una sorpresa que la documentación canónica de la esfinge no dé un ejemplo de líneas múltiples en parámetros , a pesar de que el documento de líneas múltiples es inevitable debido a la guía de 79 caracteres en PEP8 .

En la práctica, teniendo en cuenta que el nombre de su parámetro en sí mismo suele ser una word o incluso snake_case_words prefijado por el ya largo de <4 or 8+ spaces> :param , sería aconsejable hacer la siguiente sangría de línea para un solo nivel (es decir, 4 espacios), que coincide con el estilo de "sangrías colgantes" que se menciona 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.
        """

PS: Puedes verlo en acción en, por ejemplo, here . Sphinx puede recoger esas cadenas de docs y generar docs sin ningún problema.

Answer 2

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

Answer 3

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

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

Answer 4

Sí, parece que cualquier sangría cómoda para ti funciona para Sphinx y pep8 no discute. Además, si no desea que la descripción sea multilínea 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
    """

Answer 5

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

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