Run doctests for `python setup.py test`

Currently `python setup.py test` doesn't run doctests (and they are not run on travis-ci).
This PR follows the suggestion in https://github.com/astropy/package-template/issues/35 and enables doctests for `python setup.py test` and fixes the existing 23 fails and 6 errors.