[WIP] improve documentation on sample generators

As pointed out by @GaelVaroquaux and @arjoly at #2828, sample generators could do with better narrative documentation, if not examples.

Here's a start towards that goal. I think I can have a go at describing and inserting plots related to the main classification/clustering and regression generators. It would be nice if someone could provide a comparative introduction to the decomposition generators.

In general, contributions are welcome.