Simplify the documentation related to the deprecation process

[zhukovgreen]

Ref #653

TODO:

• Solve code review #653 (review)
• split the deprecation doc into parts (tutorial, generica info, ...) and put it into the right places so people can find it intuitively
  • do not forget about contribution & coding guidelines
• specify better what is covered by deprecation process
• #653 (comment)
• #653 (comment)
• #653 (comment)
• consider remove the "Additional various outputs of snactor and leapp" bottom part of the doc, or consolidate it....
• explain better the use of the stack_level_offset parameter of the @deprecated decorator.
• Fix supress_deprecation decorator to handle generators (yield) as well or document the limitation

[pirat89]

Just a note, that it's problematic to suppress deprecation for generators directly. The deprecation has to be in such a case suppressed now one level above the generator. E.g. this will not work:

@suppress_deprecation(Foo)
def Bar():
    for i in range(5):
        yield Foo(val=i)

But this works:

def bar():
    for i in range(5):
        yield Foo(val=i)

@suppress_deprecation(Foo)
def foobar():
    return list(*bar())