Please see #19839

This is a different issue than #19839.

I think there is nothing we can do about this on the Matplotlib side. With the @_api.deprecated decorator we intentionally warn if somebody uses these attributes, because it will be removed in the future. Your sphinx extension accesses these attributes, so you get the warning.

You could filter out MatplotlibDeprecationWarning for your doc builds. That should be ok, because at worst docs could fail to build once we remove deprecated stuff. But then you can still adapt without affecting your users.

Alternatively, if you are sure that nobody accesses these attributes in your subclass, you can overwrite them

class SpecialPolygon(Polygon):
    validCap = None

The deprecated properties will be removed in matplotlib 3.6. Once that gets your minimum dependency, you can remove the workaround again.

Thanks for the response. I did try to not inherit the docstring but to no avail. I'll try your suggestion when you get the chance, though right now RTD isn't complaining, but maybe it will again when the monkeypatch in #19839 is reverted. 🤷

This does not directly have to do with docstrings. The warning will occur if you access the property. - Whether your sphinx extension does that or not somewhat depending on the docstring I cannot tell. The monkey-patch should not affect the deprecation warning.

I'll leave this closed as I don't think it's actionable from our side. But you are welcome to report back if the issue comes back again.

That makes sense, I am okay with closing this issue.

To wrap things up, unfortunately #19850 (comment) does not work for us.

I guess there is no reason for sphinx-automodapi to access all the attributes but it is not a rabbit hole I want to jump in currently.

@pllim Sorry I'm late to the party, but it may make sense to silence specifically DeprecationWarning's coming specifically from whatever extension module is throwing these errors.

For example, for sphinx-autodoc, the following filter works:

# make sure to ignore warnings that stem from simply inspecting deprecated
# class-level attributes
warnings.filterwarnings('ignore', category=DeprecationWarning,
                        module='sphinx.util.inspect')

This is basically a perfect storm in terms of Python warning semantics. There really is no reasonable way for sphinx (or any other "autodoc" style code) to parse the docstrings of all attributes of a class without a getattr(cls, attr) call, but there's also no reasonable way for us to trigger a DeprecationWarning without doing so on getattr(cls, attr).

I guess there is no reason for sphinx-automodapi to access all the attributes but it is not a rabbit hole I want to jump in currently.

I would say to the contrary, if I were you I would just silence the warnings at the getattr site. In fact, I should probably open a PR that does exactly that for sphinx-autodoc....