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.
Merge pull request #1604 from jean/doc-edits

Doc edits