Doctests – again

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: 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:

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:

make doctest

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:


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s