Sphinxify docstring

[AstraLuma]

deprecated.sphinx.deprecated didn't have a very good docstring

[tantale]

Unlike other Sphinx decorators, the @deprecated decorator can be a decorator factory (with parameters) or a basic decorator (without parameter). I have to check if the second scenario (without parameter) makes sense.

[tantale]

The decoration of the following functions is bad.

No parameter at all:

@deprecated
def bad1():
    pass

Missing version argument:

@deprecated(reason="bad reason")
def bad2():
    pass

As a conclusion, I will change the signature of the Sphinx @deprecated decorator to reflect the valid use cases.