DOC/TST: Add some form of doctesting

[paddyroddy]

docstest is a nice way of checking examples in function signatures. Some of the docs have examples but we could benefit from them as tests.

[lucascolley]

there is also https://github.com/scipy/scipy_doctest

[lucascolley]

PR welcome to add one of these! I don't plan to work on it soon though.