Deprecation warning when building API doc for Polygon subclass

We started seeing deprecation warning while building doc and unfortunately we have set ReadTheDocs build to fail on warnings. After some investigation, it turned out that this is the perfect storm of the following conditions:

We have a class inheriting from matplotlib.patches.Polygon.
Sphinx automatically inherits docstrings for subclasses, which is desirable for this case.
We use a Sphinx extension calling getattr(obj, attr, *defargs).
You have deprecated validCap and validJoin here:

matplotlib/lib/matplotlib/patches.py

Lines 42 to 52 in 7f9d84a

    
           @_api.deprecated("3.4") 
        
           @_api.classproperty 
        
           def validCap(cls): 
        
               with _api.suppress_matplotlib_deprecation_warning(): 
        
                   return mlines.Line2D.validCap 
        
           @_api.deprecated("3.4") 
        
           @_api.classproperty 
        
           def validJoin(cls): 
        
               with _api.suppress_matplotlib_deprecation_warning(): 
        
                   return mlines.Line2D.validJoin

I am not sure what is the best fix. I can maybe overwrite the docstring of those two methods in subclasses but it is not elegant. Advise is appreciated. Thanks!

xref astropy/astropy#11458 and astropy/sphinx-automodapi#125

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

@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....

Navigation Menu

Repository navigation

Deprecation warning when building API doc for Polygon subclass #19850

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

	@_api.deprecated("3.4")
	@_api.classproperty
	def validCap(cls):
	with _api.suppress_matplotlib_deprecation_warning():
	return mlines.Line2D.validCap

	@_api.deprecated("3.4")
	@_api.classproperty
	def validJoin(cls):
	with _api.suppress_matplotlib_deprecation_warning():
	return mlines.Line2D.validJoin

Deprecation warning when building API doc for Polygon subclass #19850

Description

Activity

jklymak commented on Apr 2, 2021

timhoffm commented on Apr 8, 2021

timhoffm commented on Apr 8, 2021

pllim commented on Apr 8, 2021

timhoffm commented on Apr 8, 2021

pllim commented on Apr 8, 2021

brunobeltran commented on May 6, 2021

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions