Overhaul of the package documentation.

Better organisation of documentation and examples.