Updated readme

I have overhauled the README file quite a bit, and updated the inline examples.

README is now in rst rather than markdown, since (1) GitHub now parses rst better than it used to; and (2) Sphinx can't read MD.