docs overhaul

[martindurant]

This is long overdue, but the ever-extending list of "features" should be replaced by a general docs rewrite, with a focus on end-user operations and examples (e.g., piskvorky/smart_open#579 (comment) ). All help appreciated! It is to be expected that going through this process will also help to fill out the API with convenience funcitons.