Move the examples docs into the code

I like the idea of having the examples in the code.  I don't necessarily
like having to scroll through all those comments to get to the code.  This
also changes the order of the documentation to summary, example, reference
versus summary, reference, example.  I think I'm okay with that because
:class links will anchor to the reference section.  Normally, seeing a
simple example first can be more useful.

This is a response to Doug's comment:
https://review.openstack.org/#/c/129937/1/doc/source/user_preference.rst

Change-Id: Ibbda909d2183edc6baeeec0bc56f01779334aabd
Merge "Move the examples docs into the code"