Wrap long lines, punctuate consistently (full stops)
Tidying docs

Wrap long lines, tweak some markup, add some TODO notes,
got rid of some sphinx warnings.