Как документировать параметры функции Python с помощью sphinx-apidoc

Question

Я пытаюсь очистить документацию по коду Python и решил использовать sphinx-doc , потому что это выглядит хорошо.Мне нравится, как я могу ссылаться на другие классы и методы с помощью тегов, таких как:

:class:`mymodule.MyClass` About my class.
:meth:`mymodule.MyClass.myfunction` And my cool function

Я пытаюсь выяснить, как документировать имена параметров в функции, так что если у меня есть такая функция:

def do_this(parameter1, parameter2):
   """
   I can describe do_this.

   :something?:`parameter1` And then describe the parameter.

   """

Какая лучшая практика для этого?

Обновление:

Правильный синтаксис:

def do_this(parameter1, parameter2):
   """
   I can describe do_this.

   :something parameter1: And then describe the variable
   """

Answer 1

Обычно «функциональные переменные» называются параметрами;).

Здесь задокументировано: http://sphinx.pocoo.org/domains.html#signatures

И ответом является :param ________

РЕДАКТИРОВАТЬ Отказ от ответственности: я никогда не использовал и не слышал о сфинксе ... Этот пост в основном "какие слова для поиска".Надеюсь, это помогло.

Answer 2

Добавление этого ответа для объединения параметров:

pydoc является базовым без специального форматирования

epydoc использует формат '@param var:'

Doxygen ориентирован на широкий диапазон языков

Sphinx использует формат ': param type var:'. Также см. больше примеров . Это было использовано для создания документации по Python 3.5 .