Move more of README into package docs

[kisielk]

We seem to get a lot of issues sprouting from the fact that README is fairly ad-hoc and the code there is not compiled and tested. I'd like to make an effort to remove most of the documentation-related bits of the README into the package documentation, and have most of the examples be runnable / testable code.

[kisielk]

The "Examples" section could link to eg: https://godoc.org/github.com/gorilla/mux#pkg-examples

[elithrar]

Agree. I do like the code in the README as it's a very popular place for newcomers to land on, and is more readable than godoc.org in many cases (better for prose, links, etc.)

I'd like to make time to use https://github.com/campoy/embedmd to help us here - we can run it in CI and build our README from {name}_example.go. Thoughts?

[kisielk]

Yeah the embedmd thing looks like it's worth a try.

[stale]

This issue has been automatically marked as stale because it hasn't seen a recent update. It'll be automatically closed in a few days.