Как написать текст справки/описания для функций Python

Недавно я начал программировать на Python. Мне нужно написать много функций, и мне было интересно, как я могу включить текст справки или описания, чтобы он отображался в инспекторе объектов spyder, когда я вызываю функцию. В MatLab это работало, помещая закомментированный текст в начало файла функции. Есть ли аналогичный метод в Python (с использованием Spyder)?


python function spyder
person user1984653    schedule 21.02.2014    source источник

Ответы (3)


arrow_upward
41
arrow_downward

По умолчанию первая строка в теле метода используется как его строка документации (или строка документации). Python будет использовать это, когда для этого метода вызывается help().

def foo(bar):
    """
    Takes bar and does some things to it.
    """
    return bar

help(foo)
foo(bar)
    Takes bar and does
    some things to it

Вы можете узнать больше о том, как это работает, прочитав PEP-258 и < href="https://stackoverflow.com/questions/3898572/what-is-the-standard-python-docstring-format">этот вопрос содержит более подробную информацию.

person Burhan Khalid    schedule 21.02.2014
comment
как это сделать для пакетов? - person Adesh Atole; 24.02.2016

arrow_upward
9
arrow_downward

(сопровождающий Spyder здесь) Есть еще пара вещей, которые вам нужно знать (помимо того, что упомянул @burhan-khalid) о самом Spyder:

  1. Если вы хотите, чтобы ваши строки документации отображались на панели справки в красивом формате, вам нужно написать их в соответствии со стандартом numpydoc, который объясняется здесь. Это набор соглашений, используемых почти всеми научными пакетами Python для написания строк документации. Это не обязательно, но мы также следуем ему при преобразовании строк документации (которые приходят в виде простого текста) в html.

  2. Вы должны использовать Ctrl+I перед именем объекта, чтобы отобразить их справку в нашей панели справки.

person Carlos Cordoba    schedule 22.02.2014
comment
Я нашел это очень полезным, спасибо! Это новое место для этого? numpydoc.readthedocs.io/en/latest/ - person uhoh; 01.01.2019

arrow_upward
3
arrow_downward

В кратком ответе. Это можно сделать, поместив текст в тройные кавычки.

'''
@param self
'''

Краткий пример можно найти по этой ссылке: https://www.jetbrains.com/help/pycharm/creating-documentation-comments.html#

Другие ответы более обширны.

person Gerardsson    schedule 15.04.2020