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

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

11 голосов
/ 03 февраля 2010

Я предпочитаю документировать каждый параметр (при необходимости) в той же строке, где я объявляю параметр, чтобы применить 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 с какими-то манипуляциями с декоратором? Есть ли другой способ?

Ответы [ 3 ]

8 голосов
/ 03 февраля 2010

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

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

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, что значительно упрощает их обработку с помощью обычных инструментов синтаксического анализа текста в docutils.

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

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

5 голосов
/ 26 августа 2013

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

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

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

1 голос
/ 03 февраля 2010

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

...