Support PEP-702 style deprecations

[12rambau]

To document my deprecation cycles, I usually use the deprecated lib. It's as simple to use as this:

from deprecated.sphinx import deprecated

@deprecated(version='1.0', reason="This function will be removed soon")
def function_three():
    '''This is the function three'''

function_three()  # warns
help(function_three)

as the decorator is changing the result of the help method, it's automatically adding information if the documentation is build with api-doc. with autoapi, as you don't load the method but only parse them, I think this is just getting ignored.

Would you think of a way to implement a workaround either from here or directly from their repository ?

[AWhetter]

This is always going to be a limitation of static analysis. We can't cater for every possible thing that can happen at runtime.

I think it would be reasonable to say that we could document which decorators a function/method is decorated with, and then it's up to the user to understand what the decorators mean. It's likely that we'll need to let users configure an allowlist/blocklist of which decorators to document. Would this cover your use case well enough?

[12rambau]

What would be the type of output ? Would it be possible to rewrite it using a custom extention and thus make it look as it shoud (.. deprecated:: something will go wrong)?

Although I agree you can't catch everything, according to github 66000+ projects use this lib, which is more than the pydata-sophinx-theme so I would say it's a pretty big deal in the documentation community.

[AWhetter]

PEP-702 introduces support for an official @deprecated() decorator (https://peps.python.org/pep-0702/). So I'm going to repurpose this issue to support that instead, whether it's imported from warnings or typing_extensions.

[12rambau]

I discussed a bit with the deprecated team, the scope of the lib is still wider than the one from PEP-702, Could I create some sort of plugin to change how this decorator is interpreted ?

Because I guess, it's just about reading the decorator itself and change the template accordingly right ?

from conf.py the parameter would be:

extra_decorator = {
    "deprecated": ".. deprecated:: {reason}"
}

Each key being the name of the decorator and the value the string to use at the end of the description using the parameter names if any.

From the parser side I check the decorators and if any I add them to the template if they are listed only. For the specific use case of PEP-702 the decorator would be in the default decorator.

[AWhetter]

Creating plugins like this would mean that how parsing is done and what libraries we use for parsing would become part of the public API. I wouldn't want to be blocked from making significant changes to the parsing code without a really good reason. I don't think supporting this one library is enough to justify that. However #444 was written to investigate using Griffe for parsing. It has support for extensions, so if we end up using Griffe then you might be able to hook into it that way.