Fix Sphinx docs warnings

@larrybradley This should fix all Sphinx warnings and makes some other minor changes.

The docs are still not very pretty, but we can fix that over the following weeks.

I'll be offline now ... once travis-ci is green you should ping Tom to merge this.