So, last time I was blogging about how I tested doctests by placing them into docstrings. This makes it easy to have code, documentation and tests for it really close to each other. Disadvantage is that the docstrings can get unwieldly over the time and complex test cases aren’t so fun to write there.
I’m trying to maintain simple documentation about the game as I code it. It can be viewed at: http://tuturto.github.com/pyherc/. The idea is that I have short tutorial about main concepts of the system, which hopefully helps others to pick up and write their own games or additions to the existing game. There are code examples too there, like in: http://tuturto.github.com/pyherc/api/actions.html
And this is really the place where doctests shine. Originally I only had the tutorial part of the page, without the final listing of all the code that I wrote about. After I noticed couple of typos in the examples, I wrote all the code as a doctest and placed it in the end of the page as a summary.
Now when I’m generating documentation I can run sphinx with command:
And it will automatically pick out all the test pieces from documentation and run them. This should help to keep the documentation up to date with the code. Instructions how to take doctests into use with sphinx can be found at: http://sphinx.pocoo.org/ext/doctest.html