clean up RST for PyPI, add some better annotations to examples