Легко документировать класс или метод в 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?
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)
Документация свойства в интерпретаторе 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 после определения. Комментарии должны быть либо на отдельной строке перед определением, либо сразу после назначения в той же строке. Последняя форма ограничивается только одной строкой.
Документируйте свободно доступные атрибуты в классе docstring или внесите их в свойства. Вы правильно документируете свойства, проблема может быть в классах 2.x и old-style, которые не поддерживают дескрипторы - наследуют от object в этом случае.
С Sphinx нотация /реструктурированный текст в ваши docstrings вы можете автоматически генерировать хорошо отформатированную документацию из источников Python. Он также поддерживает аргументы и возвращает значения для функций - никаких полей, насколько я знаю, но вы можете легко создать список для них.