Automatically run all examples in documentation as doctests

[goerz]

All "doctest examples" in the handwritten parts of the documentation (the .rst files in ./docs) should be run automatically by the test suite. This is mostly to guarantee that the documentation is up to date with the latest version of the code. Currently, significant parts of the documentation are not* up to date, so those examples will need to be fixed first.

Note that code examples in docstrings (i.e. the API documentation) are already automatically tested.

[goerz]

Created feature/rstdoctest branch to track this