Fix up the docs based on recent README fixes

[cjrh]

Based on this PR that changed the README, docs should also be fixed up: #203

[cjrh]

I made these fixes in #223. Once that is merged I'll remove all the code in the README, so that we keep all code examples in the docs where they'll also be tested.