Fix docs links, formatting and pep8

I tried to fix some obviously broken docstring formatting (broken API links, examples, etc.) 

And as the codes files were open I took the liberty for doing some PEP8 formatting, too.