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

Question

Легко документировать класс или метод в 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?

Answer 1

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

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

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

class Foo(object):
  velocity = 1  
  """Foo's initial velocity - class variable"""

  def __init__(self, args):
    self.location = 0.0 
    """Foo's initial location - instance variable"""   

(Правка: исправлена ​​вторая строка документа)

Answer 2

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

>>> 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:. Строки документации для атрибутов могут быть заданы как комментарии, предшествующие атрибуту, но с использованием двоеточия после хеш-метки, EG #: the foo attribute. Из документации автодока Sphinx:

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

Answer 3

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

Answer 4

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