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

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

: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 
    """

источник

2012-03-02 Adam Morris

Эти названия называются «списками информационного поля». См. Также http://stackoverflow.com/questions/4547849/good-examples-of-python-docstrings-for-sphinx – gotgenes

Проверьте [Наполеан] (http://www.sphinx-doc.org/en/stable /ext/napoleon.html) для Sphinx, который позволяет вести строки документа в любом стиле [Google или Numpy] (http://www.sphinx-doc.org/en/stable/ext/napoleon.html#google-vs- numpy), оба из которых выглядят лучше, чем простой Sphinx. – cbare

Также интересует: http://www.pydev.org/manual_adv_type_hints.html –

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

Он никогда описываемая здесь: http://sphinx.pocoo.org/domains.html#signatures

И ответ :param ________

EDIT Отказ от ответственности: Я не использовал и не слышал сфинкса ... Это сообщение является главным образом «, какие слова для поиска «. Надеюсь, это помогло.

источник

2012-03-02 14:02:51 Crisfole

Спасибо ... Я искал неправильную вещь. В какой-то момент я пробовал параметр, но продолжал получать ошибки и не понимал, что синтаксиса не было: param: 'variable1', но: param variable1: –

http://sphinx-doc.org/domains.html#id1 и https://pythonhosted.org/an_example_pypi_project/sphinx.html#function-definitions – ddotsenko

Условные обозначения для документирования сложных параметров (списки, диктофоны и т. д.) - https://www.jetbrains.com/pycharm/webhelp/type-hinting-in -pycharm.html – ddotsenko

Добавление этого ответа консолидировать варианты:

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

epydoc использует формат «@param вара:»

Doxygen ориентирован на большее количество языков

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

источник

2015-09-21 16:37:29

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

ответ

Смежные вопросы