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: 4656 (since July 30th)
- Plays in last week: 5
- Published: 59 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
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.
Very interesting
That settled about a dozen big issues that I've been confronting...
Thanks!
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
