support the @deprecated decorator

[DetachHead]

Problem Description

python now has a @deprecated decorator: https://peps.python.org/pep-0702/

in pdoc it's just treated like a normal decorator and is quite easy to miss:

Proposal

display the deprecated message as a warning, something like this:

Additional context

the decorator isn't coming to python until 3.13, but it can currently be used older python versions by importing it from typing_extensions. vscode already supports it too

[mhils]

I like the idea, but implementation-wise I don't particularly like decorators having a magic effect on docstrings. One viable workaround here could be to add the decorator name to the CSS class and then apply a CSS filter like so:

section:has(.decorator-deprecated) {
    filter: grayscale(1) opacity(0.8);
}

This is just one idea - we could also do a CSS thing that highights the @deprecated annotation like so:

.decorator-deprecated {
    background: #ffe91d78;
    margin-left: -15px;
    padding-left: 15px;
    margin-right: -5px;
    padding-right: 5px;
}

Maybe that's better because it's less likely to run into accessibility issues. :)