Итак, 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
"""
Что такое синтаксис/соглашение для этого? Должен ли я отступать или нет? будет ли он разбит реструктурированный текст?
Похоже, что если вы отступали хотя бы на один уровень относительно директивы: param:, он не нарушит рендеринг реструктурированного текста. Лично я предпочитаю выравнивать все дополнительные строки до первой строки описания этого параметра. Обратите внимание, что reST также игнорирует новые строки и выводит текст без разрывов строк.
К сожалению, я не смог найти источник, который мог бы упомянуть об этой проблеме, или привести пример многострочного: param: description.
просто новая строка, в которой вы хотите разбить строку.
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
"""
Да, кажется, что вам удобнее работать с отступами для 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
"""