Многострочное описание описания параметра в docstring python

Итак, reStructuredText - это рекомендуемый способ для кода Python документации, если вы достаточно стараетесь, вы можете найти в документации sphinx как нормализовать документацию подписи функций. Все приведенные примеры однострочный, но что, если описание параметра многострочно, как показано ниже

def f(a, b):
    """ Does something with a and b

    :param a: something simple
    :param b: well, it not something simple, so it may require more than eighty
              chars
    """

Что такое синтаксис/соглашение для этого? Должен ли я отступать или нет? будет ли он разбит реструктурированный текст?

Ответ 1

Похоже, что если вы отступали хотя бы на один уровень относительно директивы: param:, он не нарушит рендеринг реструктурированного текста. Лично я предпочитаю выравнивать все дополнительные строки до первой строки описания этого параметра. Обратите внимание, что reST также игнорирует новые строки и выводит текст без разрывов строк.

К сожалению, я не смог найти источник, который мог бы упомянуть об этой проблеме, или привести пример многострочного: param: description.

Ответ 2

просто новая строка, в которой вы хотите разбить строку.

def f(a, b):
    """ Does something with a and b

    :param a: something simple
    :param b: well, it not something simple, 
              so it may require more than eighty
              chars
    """

Ответ 3

Да, кажется, что вам удобнее работать с отступами для Sphinx, и pep8 не спорит. Кроме того, если вы не хотите, чтобы описание было многострочным в подготовленной документации, вы можете использовать традиционные линейные ошибки Python с помощью \:

 def f(a, b):
    """ Does something with a and b

    :param a: something simple
    :param b: well, it not something simple, so it may require more \
              than eighty chars
    """