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
Our authors tell us that feedback from you is a big motivator. Please take a few moments to let them know what you think of their work.
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.
:Classes:
DBObject
Barber
Style
Client
"""
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('styles.id')),
Column('barber_id', Integer, ForeignKey('barbers.id')),
)
client_table = Table('clients', metadata,
Column('id', Integer, primary_key=True),
Column('name', String(40)),
Column('style_id', Integer, ForeignKey('styles.id'))
)
queue_table = Table('queue', metadata,
Column('id', Integer, primary_key=True),
Column('timestamp', TIMESTAMP),
Column('client_id', Integer, ForeignKey('clients.id')),
)
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
:arguments:
config
configuration dictionary which may be overridden by subclasses
**Usage**
>>> 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: 3474 (since July 30th)
- Plays in last week: 15
- Published: 25 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.
All comments excluding tick-boxed quick-comments
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
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
Thanks again.
Great videos! Thanks so much.
Thanks a lot for fine tips!
I normally don't like videos, but your sphinx demo was great!
nice tutorial, thanks
really good tutorial
Really useful, thanks.
Thanks for the awesome tutorial! I've known this stuff was possible for a while. Now I know how to do it.
Sweet vid! I was just thinking about giving sphinx a go, but after watching this it's a definite.
Thanks for taking the time!
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
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!
I just want to see the third video.
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.
Sam
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 "sphinxme.py". Is it a script you have written yourself, or comes it with sphinx?
And a suggestion: Maybe you could show some links (like sphinx.pocoo.org) in a higher font-size.
Thanks for this video
Maximilian
Great tutorial! Are you planning on doing one about sphinx.ext.coverage? It seems to still lack documentation.
Insightful ! (as always...)
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.
hello,
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:
aaa
bbb
ccc
but I can get only
aaa bbb ccc
or
aaa
bbb
ccc
I'll be really grateful for help.
Thanks in advance,
Lena
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 sjhook@gmail.com.
Cheers, Simon
In reponse to simon:
You probably forgot to do python setup.py 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 pythontutorials.googlecode.com . The files which you are specifically asking for are here: http://pythontutorials.googlecode.com/svn/tutorials/barbershop/docs/source/
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.
cheers.
-chris
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 (conf.py, 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.
Simon
