Change the way doctests are loaded in test.py

(this is based on #192 so please merge that first before looking at this huge diff)

There were a lot of doctests missing from our tests,
which became very apparent after latest set of refactoring.

This patch moves from doctest.DocTestSuite to doctest.DocFileSuite
and is run on every python file in our project.

This exposed some doctests that were not being run before because of syntax
errors and the fix for those is included in the same commit.