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:

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"""   

(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.

>>> 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

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.