docs: use doctests about documentation HOT 3 OPEN

From @AbdealiJK on February 24, 2016 4:25

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.

from documentation.

From @Redridge on February 24, 2016 18:9

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

from documentation.

From @sils1297 on February 24, 2016 18:11

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.

from documentation.