Minor documentation fixes [and possibly unwanted changes ;)]

This pull request fixes a few typos, and fixes some reST/sphinx warnings.

I've left the branch as a long series of changes to make it easier for you to cherry-pick out any you'd like and ignore the rest.  I can rebase if it would be helpful.

Thanks,

James