Doctest fixes for v0.2rc

This addresses most of the issues raised directly in https://github.com/astropy/astroquery/issues/384, but is not a PR on that issue.

I've gone through with a hack doctest (`make_doctests.py`) and tested all of the extracted code from the .rst docs.  I have *not* tested the docstrings!

(this PR mixes in some actual code fixes that I could separate into other PRs for cleanliness, but it's too much effort atm)

@cdeil
Add a short docstring at the top what this script is?