У Сфинкса, там способ зарегистрировать параметры наряду с объявлением их?
Я предпочитаю документировать каждый параметр (по мере необходимости) на той же строке, где я объявляю параметр для применения 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
):
...
Как я могу постараться не повторять, что параметры в документе представляют в виде строки и сохраняют объяснения параметра?
Я хочу избежать:
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 со своего рода управлением декоратора? Есть ли некоторый другой путь?
2 ответа
Я бы сделал это.
Начиная с этого кода.
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 по умолчанию и даже помечают переменные / методы в той области, которая, по мнению IDE, не соответствует объявленному типу.
Обратите внимание на лишнюю запятую в коде; это просто для того, чтобы все было согласовано. Это не вредит и может упростить ситуацию в будущем.
Вы также можете попробовать использовать компилятор Python, чтобы получить дерево синтаксического анализа, изменить его и выпустить код обновления.Я сделал это для других языков (не для Python), поэтому я немного знаю об этом, но не знаю, насколько хорошо это поддерживается в Python.
Кроме того, это однократное преобразование.
Исходные встроенные комментарии в определении функции на самом деле не следуют за DRY, потому что это комментарий, сделанный на неформальном языке и непригодный для использования никакими, кроме самых сложных инструментов.
Комментарии Sphinx ближе к DRY, потому что они написаны на языке разметки RST, что значительно упрощает их обработку с использованием обычных инструментов анализа текста в документах .
Это СУХОЕ, только если инструменты могут его использовать.
Полезные ссылки: https://pythonhosted.org/an_example_pypi_project/sphinx.html#function-definitions http://sphinx-doc.org/domains.html#id1
Вы не можете сделать это без препроцессора, поскольку комментарии для Python не существуют после того, как исходный код скомпилирован. Чтобы не повторяться, удалите комментарии и задокументируйте параметры только в строке документации, это стандартный способ документировать свои аргументы.