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

Я предпочитаю документировать каждый параметр (по мере необходимости) в той же строке, где я объявляю параметр, чтобы применить D.R.Y.

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

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 с каким-то образом обработкой декоратора? Есть ли другой способ?

Ответы

Ответ 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
   """
    ...

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

Много хороших IDE Python (например, PyCharm) понимают стандартную нотацию Sphinx param и даже флаги vars/methods в области, которую, по мнению IDE, не соответствует объявленному типу.

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

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

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

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

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

Это только СУХОЕ, если инструменты могут его использовать.

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

Ответ 2

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

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

Я не уверен, была ли еще какая-либо работа по их применению к Sphinx.

Ответ 3

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