Overhaul of the package documentation.

Better organisation of documentation and examples.
Merge pull request #18 from ajdawson/documentation-overhaul

Overhaul of the package documentation.