Run documentation examples using doctest

[siranipour]

Often times I stumble across examples that no longer working because a new dependencies has been introduced somewhere upstream in the execution graph.

We should check that all docstrings works using doctest, however, if I run it now I get a lot of tests failing because the tests are not in the correct format.

[Zaharid]

I think doing something in that direction would be good. We still have a relatively small fraction of the api exposed in tests and this would help quite effectively.

Is there a way of making doctest run on marked examples only rather than everywhere?