Improve online documentation

[jstac]

The documentation would be better if functions and classes all had at least one example and possibly more. E.g., see the examples here:

http://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.expon.html

There is a section devoted to examples. In the NumPy / SciPy docs, I find this section is often more useful than any other kind of documentation. I propose we push towards improving our documentation in this way.