В SPHINX есть ли способ документировать параметры вместе с объявлением их?

Question

Я предпочитаю документировать каждый параметр (по мере необходимости) в той же линии, где я объявляю параметр, чтобы применить СУХОЙ

Если у меня есть код так:

def foo(
        flab_nickers, # a series of under garments to process
        has_polka_dots=False,
        needs_pressing=False  # Whether the list of garments should all be pressed
   ):
    ...

Как я могу избежать повторения параметров в строке DOC и сохранить пояснения параметров?

Я хочу избежать:

def foo(
        flab_nickers, # a series of under garments to process
        has_polka_dots=False,
        needs_pressing=False  # Whether the list of garments should all be pressed
    ):
    '''Foo does whatever.

    * flab_nickers - a series of under garments to process
    * needs_pressing - Whether the list of garments should all be pressed.
      [Default False.]

Это возможно в Python 2.6 или Python 3 с каким-то декоратором манипуляции? Есть ли какой-то другой путь?

Answer 1

Я бы сделал это.

Начиная с этого кода.

def foo(
        flab_nickers, # a series of under garments to process
        has_polka_dots=False,
        needs_pressing=False  # Whether the list of garments should all be pressed
   ):
    ...

Я бы написал парсер, который захватывает определения параметра функции и создает следующее:

def foo(
        flab_nickers, 
        has_polka_dots=False,
        needs_pressing=False,
   ):
   """foo

   :param flab_nickers: a series of under garments to process
   :type flab_nickers: list or tuple
   :param has_polka_dots: default False
   :type has_polka_dots: bool
   :param needs_pressing: default False, Whether the list of garments should all be pressed
   :type needs_pressing: bool
   """
    ...

Это некоторое красивое прямое переработка REGEX различных аргументов струнных шаблонов для заполнения шаблона документации.

Много хороших IDES Python (например, Pycharm) понять SPHINX по умолчанию param Обозначение и даже флаг Варс / Методы в области применения, что IDE думает, не соответствует заявленному типу.

Обратите внимание на дополнительную запятую в коде; Это только для того, чтобы сделать все согласованные. Это не повредит, и это может упростить вещи в будущем.

Вы также можете попробовать и использовать компилятор Python, чтобы получить дерево разбора, пересмотреть его и испускать код обновления. Я сделал это для других языков (не Python), поэтому я немного знаю об этом, но не знаю, насколько хорошо поддерживается в Python.

Кроме того, это одноразовое преобразование.

Оригинальные встроенные встроенные комментарии в определении функции не соблюдают сухих, потому что это комментарий, в неформальном языке и непригодным для использования любыми, но самыми сложными инструментами.

Комментарии SPHINX ближе к сухому, потому что они на языке разметки RST, что делает их намного проще обработать с использованием обычных текстовых инструментов для анализа в docutils.

Это только сухие, если инструменты могут использовать его.

Полезные ссылки:https://pythonhosted.org/an_example_pypi_project/sphinx.html#fpunction-definitions. http://sphinx-doc.org/domains.html#id1.

Answer 2

Аннотации предназначены для частично решить эту проблему в Python 3:

http://www.python.org/dev/peps/pep-3107/

Я не уверен, что произойдет какая-либо работа в применении их в Сфинкс.

Answer 3

Вы не можете сделать это без препроцессора, поскольку комментарии не существуют для Python после того, как источник был скомпилирован. Чтобы не повторять себя, удалите комментарии и документируйте параметры только в DOCSTRING, это стандартный способ документировать ваши аргументы.