1

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?

Psirus
  • 1,425
  • 1
  • 14
  • 22
  • 1
    Your code contains two classes. There are no subclasses and no functions. Please clarify. – mzjn Mar 12 '14 at 18:18
  • Well, the every body has a surface connected to it, i.e. there are no surfaces without bodies. Thats why there are quotation marks around the subclass; I didn't know what to call it. And there is a method called `get_surface_area`?! – Psirus Mar 12 '14 at 19:01
  • OK, a Body object holds a reference to a Surface object. And when you say function, you mean method. But I still don't understand what the problem is. – mzjn Mar 12 '14 at 19:10
  • If you want to document the instance variables, then this answer might help: http://stackoverflow.com/a/8659919/407651. – mzjn Mar 12 '14 at 19:25
  • Thanks, that was very helpful. Now I can at least say `:ivar surface: interface for :class:`example.Surface` and have a link to the class. Still unsure if it is clear to the reader that you can do `mybody.surface.get_surface_area()` instead of `mysurface = Surface(mybody); mysurface.get_surface_area()`. – Psirus Mar 13 '14 at 01:17

1 Answers1

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
mzjn
  • 48,958
  • 13
  • 128
  • 248