How To Document Fields And Properties In Python?

It's easy to document a class or method in Python: class Something: ''' Description of the class. ''' def do_it(self): ''' Description of the method. ''' pass class

Solution 1:

Python has a PEP (257) that defines Docstring Conventions. Regarding documentation of attributes, it states:

String literals occurring immediately after a simple assignment at the top level of a module, class, or __init__ method are called "attribute docstrings".

So the following are considered documented attributes:

classFoo(object):
  velocity = 1"""Foo's initial velocity - class variable"""def__init__(self, args):
    self.location = 0.0"""Foo's initial location - instance variable"""

(Edit: Fixed second docstring)

Solution 2:

Documentation of a property in the python interpreter using help works fine for me, see proprerty documentation. Note: IPython's magic help operator, ?, did not display the property docstring.

>>>classfoo(object):>>>def__init__(self, bar):>>>       self._bar = bar>>>   @property>>>defbar(self):>>>"""bar property""">>>return self._bar>>>help(foo.bar)
Help on property:

    bar property

In Sphinx you must use the :members: directive to document properties, see autodoc documentation. Works like a charm for me!

Attributes will also be documented by Sphinx if :members: is used. Docstrings for attributes can be given as comments preceding the attribute, but using a colon following the hash mark, EG #: the foo attribute. From the Sphinx autodoc documentation:

For module data members and class attributes, documentation can either be put into a comment with special formatting (using a #: to start the comment instead of just #), or in a docstring after the definition. Comments need to be either on a line of their own before the definition, or immediately after the assignment on the same line. The latter form is restricted to one line only.

Solution 3:

Document freely accessible attributes in the class docstring or make them into properties. You're documenting properties properly, the problem might be in 2.x and old-style classes, which don't support descriptors — inherit from object in that case.

Solution 4:

With Sphinx notation / Restructured Text in your docstrings you can generate nicely formatted documentation from you Python sources automatically. It also supports arguments and return values for functions - no fields as far as I know, but you can easily create a list for them.