How do I document "sub-classes" using sphinx and autodoc?

Question

Assuming I have a file example.py with the following contents:

class Body(object):
    """Representation of a geometric body."""
    def __init__(self):
        self.surface = Surface(self)

class Surface(object):
    """Representation of a geometric surface."""
    def __init__(self, body):
        self.body = body

    def get_surface_area(self):
        """ Calculate surface area of the body """
        print 4

mybody = Body()
mybody.surface.get_surface_area()

When I do

.. automodule:: example
    :members:

I get all the two classes and the function documented. However, how would I go about pointing out the intended usage of my class, i.e. mybody.surface.get_surface_area() and also have the correct links in place?

Answer 1

I'm not completely sure if this is what you want, but here is a suggestion on how you could document your classes:

class Body(object):
    """Representation of a geometric body.

      :ivar surface: a :class:`example.Surface` instance 

      Usage example:

      >>> mybody = Body()
      >>> mybody.surface.get_surface_area()
      >>> 4

      Another way of doing it:

      >>> mybody = Body()
      >>> mysurface = Surface(mybody)
      >>> mysurface.get_surface_area()
      >>> 4

    """
    def __init__(self):
        self.surface = Surface(self)  

class Surface(object):
    """Representation of a geometric surface.

     :ivar body: The supplied :class:`example.Body` instance

    """
    def __init__(self, body):
        self.body = body             

    def get_surface_area(self):
        """ Calculate surface area of the body """
        print 4