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). I'd like to eventually add automatic flake8 checking for future pull-requests, but don't know how, yet.

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.