feature: highlight functions decorated with `@deprecated`

Is your feature request related to a problem? Please describe.

I am maintaining a library where I am using pythons new @deprecated decorated, which is useful as LSP's can pick this up and provide feedback to users that the functions they are using are deprecated. I also need to keep existing documentation around as users may not know what the function does, in order to consider either the recommended alternative or some alternate solution (I need to keep old docstrings visible.

The (minor) problem is I need to duplicate both the recommended alternative in both the docstring and in the @deprecated decorator.

from typing_extensions import deprecated # pre 3.13

@deprecated("Please use `g(value)` instead")  # <- For indicating to people in code
def f(value: int) -> int:
    """
    !!! warning "Deprecated"                   # <- For indicating to people in docs
        Please use `g(value)` instead.

    Doubles a value.
    """
    return g(value)

Describe the solution you'd like

I would like to see an explicit indication in the documentation that shows that the function/method is deprecated with the decorator with the inner message as well. I naively would like the exact same as would be produced for above, however this raises some questions such as, what to do if someone already has a !!! warning "Deprecated", should they just be duplicated? What happens if the string in the deprecated block contains markdown/html?

Describe alternatives you've considered

The alternative is just duplication for now. It's relatively minor, but it would be a nice quality of life.

Additional context

PEP 702 – Marking deprecations using the type system This already seems to be supported for in-editor warnings for at least vs-code but also pyright, which is the open-source version of vs-code's LSP.

mkdocstrings / python