Improve documentation

[tdiethe]

Now that the documentation is automatically populated on readthedocs, it would be a good time to improve the documentation. Some tasks:

• introductory documentation
• documentation for each package/module (rather than just classes and methods)
• fix bugs such as missing spaces between text and parameters