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

Я пытаюсь очистить мою документацию по коду 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.

   """

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

Update:

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

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

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

Ответы

Ответ 1

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

Здесь описано: http://sphinx.pocoo.org/domains.html#signatures

И ответ :param ________

EDIT Отказ от ответственности: я никогда не пользовался или не слышал о sphinx... Этот пост - это в основном "какие слова искать". Надеюсь, что это помогло.

Ответ 2

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

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

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

Doxygen ориентирован для большего диапазона языков

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