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?

Your code contains two classes. There are no subclasses and no functions. Please clarify. — mzjn
– mzjn, Commented Mar 12, 2014 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
– Psirus, Commented Mar 12, 2014 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
– mzjn, Commented Mar 12, 2014 at 19:10
If you want to document the instance variables, then this answer might help: stackoverflow.com/a/8659919/407651. — mzjn
– mzjn, Commented Mar 12, 2014 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
– Psirus, Commented Mar 13, 2014 at 1:17

mzjn · Accepted Answer · 2014-03-13 16:34:17Z

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

That's probably what I'm going to do. Thank you for taking the time!

Collectives™ on Stack Overflow

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

1 Answer 1

1 Comment

Linked

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

1 Comment

Linked

Related