docs: use doctests

_From @Redridge on February 15, 2016 11:40_

In order for the docs to be correct, the code that the docs contain must be correct.
For that matter the docs should be all doctest stable. [doctest](https://pytest.org/latest/doctest.html)
Rewrite/Imporve the docs such that they use doctest

difficulty/low

_Copied from original issue: coala-analyzer/coala#1498_