Name: [8039] percious
Member: 69 months
Authored: 4 videos
Description: ...

Using Sphinx and Doctests to provide robust documentation [ID:817] (3/3)

in series: Agile Development Tools in Python

video tutorial by percious, added 07/08

(Showmedo is undergoing major changes. To report any problems viewing the videos please email us and include browser and OS specifics. Cheers - Kyran.)

Sphinx is a fairly new package that people have been using to document their packages. Even the newest Python 2.6 documentation has been converted to sphinx. This demo shows how you can use sphinx to document your own program.

Barbershop Model Module

This contains all of the definitions for the model of the barbershop,
including the tables, classes and mappers.






from sqlalchemy import String, Integer, ForeignKey, Table, Column, MetaData, TIMESTAMP
from sqlalchemy.orm import mapper, relation, backref, class_mapper, object_mapper

metadata = MetaData()

barber_table = Table('barbers', metadata,
                     Column('id', Integer, primary_key=True),
                     Column('name', String(40))
style_table = Table('styles', metadata,
                    Column('id', Integer, primary_key=True),
                    Column('name', String(40))
barber_style_table = Table('barber_style', metadata,
                     Column('style_id', Integer, ForeignKey('')),
                     Column('barber_id', Integer, ForeignKey('')),
client_table = Table('clients', metadata,
                    Column('id', Integer, primary_key=True),
                    Column('name', String(40)),
                    Column('style_id', Integer, ForeignKey(''))
queue_table = Table('queue', metadata,
                    Column('id', Integer, primary_key=True),
                    Column('timestamp', TIMESTAMP),
                    Column('client_id', Integer, ForeignKey('')),

class DBObject(object):
    This is the DBObject class which all other model classes rely on.
    It allows us to instantiate an object with attributes simply by passing
    them into the constructor.

    def __init__(self, **kw):
        for item, value in kw.iteritems():
            setattr(self, item, value)

    def json(self, **config):
        This returns a simple json dictionary of the first-level objects
        in an sql-mapped object

           configuration dictionary which may be overridden by subclasses


        >>> obj = DBObject(a=1, b=2)
        >>> obj.json()
        "{'a': 1, 'b': 2}"

        d = {}
        for prop in self.__dict__:
            if not prop.startswith('_'):
                d[prop] = getattr(self, prop)
        return str(d)

class Barber(DBObject):
    """Barber Object"""

    def never_tested(self):
       raise Exception('you finally figured it out!')

class Style(DBObject):pass
class Client(DBObject):pass
class QueueItem(DBObject):pass

mapper(Barber, barber_table, properties={'styles':relation(Style, secondary=barber_style_table, backref='barbers')})
mapper(Style, style_table)
mapper(Client, client_table, properties={'style':relation(Style)})
mapper(QueueItem, queue_table, properties={'client':relation(Client)})

Got any questions?

Get answers in the ShowMeDo Learners Google Group.

Video statistics:

  • Video's rank shown in the most popular listing
  • Video plays: 4784 (since July 30th)
  • Plays in last week: 5
  • Published: 69 months ago

Thank-yous, questions and comments

If this video tutorial was helpful please take some time to say thank-you to the authors for their hard work. Feel free to ask questions. Let the author know why their video tutorial was useful - what are you learning about? Did the video tutorial save you time? Would you like to see more?

You may also want to see our ShowMeDo Google Group to speak to our active users and authors.

Your email address will not be published.

Show some quick comments >>

All comments excluding tick-boxed quick-comments

40. R. Mark Sharp Tue, 11 Jan 2011 07:24

If you moved your image to the top right, I think it would be easy to follow what you are doing in the terminal.

Nice job.

39. Francesco Bartoli Wed, 13 Oct 2010 03:56

Very interesting

38. John Tibbetts Sat, 02 Oct 2010 11:48

That settled about a dozen big issues that I've been confronting...


really cool... enjoyed your demo.. had spend the whole day trying to get my sphinx docs working...

Excellent Tutorial Percious!

With your video I got up and running for documenting

my code with Sphinx. Especially I didn't know how to

add the little twicks to make Sphinx find my source

code and extract the docstrings, so this video really

helped me a lot.

Thanks for nice video on Spinx

Fantastic, this video was super useful in explaining the concepts. Exactly what I needed.

Excellent work! Very helpful

32. John Graves Sun, 07 Feb 2010 23:15

Couldn't figure out what the :mod: was for in the title of your module rst file. Is that just a convention of yours or a sphinx directive?

Very helpful tutorial !

More on sphinx , like building complex documents ( with figures, maths etc and more on using sphinx itself ) will be greatly appreciated

Thank you

30. Jonathan Fri, 22 Jan 2010 17:16

Thanks again.

29. PEIWEI WU Fri, 15 Jan 2010 17:29

Great videos! Thanks so much.

28. anonymous Thu, 17 Dec 2009 19:13

Thanks a lot for fine tips!

27. anonymous Tue, 01 Dec 2009 22:01

I normally don't like videos, but your sphinx demo was great!

26. anonymous Mon, 26 Oct 2009 13:07

nice tutorial, thanks

25. anonymous Sat, 24 Oct 2009 04:15

really good tutorial

24. anonymous Sun, 11 Oct 2009 12:26

Really useful, thanks.

23. anonymous Tue, 22 Sep 2009 00:22

Thanks for the awesome tutorial! I've known this stuff was possible for a while. Now I know how to do it.

22. anonymous Tue, 01 Sep 2009 00:09

Sweet vid! I was just thinking about giving sphinx a go, but after watching this it's a definite.

Thanks for taking the time!

21. anonymous Mon, 24 Aug 2009 07:30

your style, while not exciting, is even... and pleasant to follow. Perhaps a bit more enthusiasm about the bits that excite you might make it more interesting. Nicely done -- roy

20. anonymous Sat, 08 Aug 2009 17:23

Excellent tutorial, I was looking a simple way to document my python modules and this was exactly what I was looking for.

Thanks a lot!

19. anonymous Wed, 22 Jul 2009 17:38

I just want to see the third video.

18. anonymous Fri, 10 Jul 2009 09:02

I was a bit put-off at the beginning because things were a bit different from what I expected. I thought it would be as simple as using epydoc for example.

However after a bit of reading on Sphinx's documentation I looked at your screencast and I managed to do what I wanted to do. So thank you very much because I think I would have given up without your help.


17. anonymous Fri, 03 Jul 2009 00:49

ShowMeDo want's me to write a feedback. I hope, you want this, too.

I really enjoyed this video - it's very informative.

Only thing i didn't understand was the "". Is it a script you have written yourself, or comes it with sphinx?

And a suggestion: Maybe you could show some links (like in a higher font-size.

Thanks for this video


16. anonymous Thu, 21 May 2009 03:49

Great tutorial! Are you planning on doing one about sphinx.ext.coverage? It seems to still lack documentation.

15. anonymous Thu, 14 May 2009 15:13

Insightful ! (as always...)

14. anonymous Thu, 07 May 2009 19:53

This may be moot since you provide source (which is very nice), but I found the font size in Wing IDE difficult to read (and I'm not a grey-beard dev). Also, I love working on a black background w/ light colors - but I found the theme/look-n-feel of your Wing IDE session hard to read (in addition to the font size). I thought the pace and example was good. I was surprised that you didn't work in auto-summary, which I heard you speak about in your pycon talk. I want to make sure though that I extend my appreciation and gratitude. (I'm giving a quick 15-min preso to my local python group and I'm happy to get info)

Thank you! Brilliant tutorial, I was having difficulty getting Sphinx generating API docs for my modules, but with this it's much easier.

11. anonymous Thu, 20 Nov 2008 07:06


I have a question. For some time I've been creating documentation for my software with Sphinx and I can't achieve one simple thing. I don't know how to add new line.

I want to have:




but I can get only

aaa bbb ccc





I'll be really grateful for help.

Thanks in advance,


Showmedo is a peer-produced video-tutorials and screencasts site for free and open-source software (FOSS)- with the exception of some club videos, the large majority are free to watch and download.

how to help » about » faq »

Educating the Open-source Community With Showmedo

Although as important as the software it supports, education and documentation are relatively neglected in the Open-source world. Coders love to code, and explaining how best to use or improve the software tends to be deferred or even sidelined.

At Showmedo we believe the community can play a vital role here and also say thanks for the tools and software that make our lives easier. If you have a piece of software you love or a programming langugage you are enthusiastic about, why not make a screencast showing others how to use it? All the stuff you wish you'd been told, the tips, tricks, insights that would have saved you time and frustration.

Screencasting is easier than you think, and we're happy to help you. You can emailus for advice or just use some of the how-to screencasts on the site. This screencasting learning-pathis a good place to start.

Kudos and Thanks for percious

By the Same Author



Showmedo's development is fairly rapid and bugs will inevitably creep in. If you have any problems please drop us a line using the contact address below. Likewise, any suggestions for improvements to the site are gratefully received.