As an alternative to doctest I wrote mkcodes, a script that pulls code blocks out of markdown files so they can be tested in a separate file.
Here's my actual test script using mkcodes:
mkcodes --github --output tests/docs/test_{name}.py docs
py.test tests
pyflakes tests
pep8 tests