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.

[oyamad]

It would be helpful if we have a style guide for the Examples section (just for a reference point).

We have a 2x2 table of choices regarding the following:

• whether include the import statement;
• if random, whether specify random_state.

Example:

With import

>>> import quantecon as qe
>>> qe.random.sample_without_replacement(5, 3)
array([2, 3, 4])

Without import

With random_state

>>> qe.random.sample_without_replacement(5, 3, random_state=1234)
array([0, 2, 1])

Without random_state