docs: use doctests

[Redridge]

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
Rewrite/Imporve the docs such that they use doctest

difficulty/low

[AbdealiLoKo]

I just went through the documentation. I'm unable to find any specific place where we can use doctests where it's not being used.
Could you give examples ? We mainly have shell commands in the doctests which py.test cannot run.

Our docs majorly talk about creating bears or Linters and stuff - and we cannot exactly run these without running a shell command like coala .... Importing stuff and running it using coala_main would just make things more complicated for the person reading the tutorial.

[Redridge]

If there is no place to run doctest then I think we can close this. I originally filed it guided by @sils1297

[sils]

I'm not sure what I was thinking but I think that I was thinking that we could migrate some existing tests into neat documentation examples which would do our docs good.

[Adrianzatreanu]

This issue was moved to coala/documentation#57