Flake8 compatibility and large documentation effort

Do not merge yet !

This pull request is ongoing. I'm putting all code through flake8 compatibility tests (manually at the moment). I should be finished in a few days (hopefully). 

While cleaning up the code, I've made a big documentation effort. I've more or less fully documented the routines I have written myself, but for the code that others have contributed the documentation is more shaky.