Как документировать поля и свойства в Python?

Легко документировать класс или метод в Python:

class Something:
  """ Description of the class. """

  def do_it(self):
    """ Description of the method. """
    pass

  class_variable = 1 # How to comment?

  @property
  def give_me_some_special_dict(self):
    """ doesn't work! Doc of general dict will be shown. """
    return {}

Но как документировать поле или свойство для использования в документах API или help?

Ответы

Ответ 1

Python имеет PEP (257), который определяет соглашения Docstring. Что касается документации атрибутов, в ней указано:

Строковые литералы, происходящие сразу после простого назначения наверху уровень модуля, класса или __init__метод называются атрибутом "строки документации.

Таким образом, считаются документально подтвержденные атрибуты:

class Foo(object):
  velocity = 1  
  """Foo initial velocity"""

  def __init__(self, args):
    self.location = 0.0 
    """Foo initial location"""

(Изменить: исправлена ​​вторая docstring)

Ответ 2

Документация свойства в интерпретаторе python с использованием справки отлично подходит для меня, см. документацию о пропристранстве. Примечание. Оператор магии справки IPython, ?, сделал не отображение docstring свойства.

>>> class foo(object):
>>>    def __init__(self, bar):
>>>        self._bar = bar
>>>    @property
>>>    def bar(self):
>>>        """bar property"""
>>>        return self._bar
>>> help(foo.bar)
Help on property:

    bar property

В Sphinx вы должны использовать директиву :members: для свойств документа, см. документацию autodoc. Работает как очарование для меня!

Атрибуты также будут задокументированы Sphinx, если используется :members:. Docstrings для атрибутов могут быть указаны как комментарии, предшествующие атрибуту, но с использованием двоеточия, следующего за хэш-меткой, EG #: the foo attribute. Из документации по autodoc Sphinx:

Для членов данных модуля и атрибутов класса документация может быть помещена в комментарий со специальным форматированием (с использованием #: для запуска комментария вместо просто #) или в docstring после определения. Комментарии должны быть либо на отдельной строке перед определением, либо сразу после назначения в той же строке. Последняя форма ограничивается только одной строкой.

Ответ 3

Документируйте свободно доступные атрибуты в классе docstring или внесите их в свойства. Вы правильно документируете свойства, проблема может быть в классах 2.x и old-style, которые не поддерживают дескрипторы - наследуют от object в этом случае.

Ответ 4

С Sphinx нотация /реструктурированный текст в ваши docstrings вы можете автоматически генерировать хорошо отформатированную документацию из источников Python. Он также поддерживает аргументы и возвращает значения для функций - никаких полей, насколько я знаю, но вы можете легко создать список для них.