Name: [8039] percious
Member: 96 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: 19 (since July 30th)
  • Plays in last week: 2
  • Published: 97 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. the north face jackets mens 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. cialis for sale in canada Wed, 13 Oct 2010 03:56

Very interesting

38. Artemide Dioscuri Tavolo 42 Desk Lamp Online Sale 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.

35. true religion owner Sat, 15 May 2010 06:28

Thanks for nice video on Spinx

34. jasa SEO, Backlink, Blogwalking murah Tue, 30 Mar 2010 14:28

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

33. Bogner Anti-Statik- Atmungsaktiv Warm Halten Women Tue, 02 Mar 2010 13:31

Excellent work! Very helpful

32. 送料無料激安定番定番 新色大人気 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?

31. Cheap Marlboro Cigarettes Online Red 40 Cartons Marlboro Cigarettes 025 Sun, 24 Jan 2010 10:33

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. marinir seo Fri, 22 Jan 2010 17:16

Thanks again.

29. 国内即発 最安値で販売中 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,


Hi Chris,

Thanks for posting the files. I realize this is a volunteer effort and really do appreciate your work. The reason I did not email you was I could not find an email address. If you would like me to go thro' your tutorials and make suggestions I would be happy to help. You can reach me

Cheers, Simon

In reponse to simon:

You probably forgot to do python develop in the barbershop package. You might take a look at my first video in this series to get a better understanding of Paste, and setuptools packaging.

Also, the source code is available at . The files which you are specifically asking for are here:

I apologize for the small text size. I will be using a larger/bolder font the next screencast I do for sure.

Keep in mind that all of these tutorials are provided by volunteer effort. Anyone viewing my tutorials is more than welcome to contact me personally if they have problems.



Review of Using Sphinx and Doctests to provide robust documentation

This tutorial is v. important especially since there is no such tutorial on the Sphinx site. Unfortunately I could not follow the tutorial, once Percious opens documents in the Wing IDE they are completely unreadable on the screen, even with a magnifying glass and the files he edits are not included in the available code listing (, index.rst, model.rst). I have a typo in one of mine and keep getting the message:

System Message: WARNING/2 (E:\windows\code\python\barbershop\docs\source\modules\model.rst, line 4)

autodoc can’t import/find module ‘barbershop.model’, it reported error: “No module named barbershop.model”,please check your spelling and sys.path

But I cannot see the problem. In order to be useful this tutorial needs to provide the files if the author is going to video Wing.

If this was done it would be a very, very useful tutorial and I do appreciate the work that went into thinking up a good tutorial.


Hi Chris,

Thanks for this excellent video. Excellent both content wise and quality wise. Sphinx is really an awesome tool and you have just made it more usable to upstart developers like me.

6. anonymous Fri, 15 Aug 2008 16:09

Great introduction to python documentation system.

I was Just investigating them and I almost settled on epydoc.Thanks to your video I'll go with sphinx instead

5. anonymous Tue, 12 Aug 2008 16:38

Review of Using Sphinx and Doctests to provide robust documentation

Great tutorial! I have been playing with Sphinx, but had not gotten into the auto-generation features yet. Thanks for posting this.

4. anonymous Tue, 05 Aug 2008 17:45

Really good screencast. Suggest you increase fontsize a bit, some text is quite hard to read.

Hi Chris, I've blogged about this entry too, it'll go out to the Planet Python blogs:


2. anonymous Fri, 01 Aug 2008 03:59

Very nice screencast... brief and lucid.

Thanks Percious!

another great screencast - turning into a must-see series. With documentation development this easy I finally have no excuses. A good number of hours sweat condensed into 10 minutes. Thanks for saving a chunk of my life!

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

Using Virtualenv and PasteScript

Great tutorial!

mac eyeshadow pallets Elegant And Sturdy Package 1pThangN4q Korea Taekwondo
76 months ago
Using Nosetests and Coverage to create robust software

thanks, for the video it helped me a lot to configure my environment using nose

where to buy bobbi brown makeup Wholesale Cheap r73STZukIE §¯§Ö§Õ§Ó§Ú§Ø§Ú§Þ§à§ã§ä§î §Ó §´§å§â§è§Ú§Ú - Novron
76 months ago

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.