Umm, how did we end up with private libraries linked in the public docs? That shouldn't have happened. https://matplotlib.org/stable/api/_enums_api.html#matplotlib._enums.CapStyle I think @brunobeltran and @timhoffm worked on this?

The use of private modules is a workaround. The classes themselves are not public, but the concepts they describe are. We need a location to document these concepts and the simplest solution is with the classes that represent these concepts. There are other ways to solve this as I've proposed in #18544, but that would require additional machinery and was not appreciated in that discussion.

as for the xref thing, I do not fully understand where the warning is coming from and need to have a closer look.

As far as I can tell, the xref issue stems from the fact that references to CapStyle and JoinStyle are relative paths, not absolute. I've found for other references in Astropy that changing `.object` to `~package.subpackage.object` resolves the issue

Circling back here... The patch suggested above did get around the ReadTheDocs "fail on warning" problem; see astropy/astropy#11466 though you still see those warnings in the log but they somehow not blocking RTD check. FYI 🤷

And for completeness: xref astropy/astropy#11458

I think this may be related to sphinx-doc/sphinx#6211 (which I basically opened based on my experience with matplotlib)?

I am bit confused why this specific dotted reference breaks your build whereas a lot of other dotted references (e.g. .Transform) don't?

@anntzer , these are the warnings (it breaks because we have RTD set to fail on warning):

MatplotlibDeprecationWarning:
The validCap attribute was deprecated in Matplotlib 3.4 and will be removed two minor releases later.
  return getattr(obj, attr, *defargs)

MatplotlibDeprecationWarning:
The validJoin attribute was deprecated in Matplotlib 3.4 and will be removed two minor releases later.
  return getattr(obj, attr, *defargs)

The code in astropy does not specifically have them, but rather a subclass inherited them. And then Sphinx tries to render docstring for inherited attributes. We also use sphinx-automodapi plugin to render it. So, it is really a perfect storm of a few things put together.

References: astropy/astropy#11458 astropy/sphinx-automodapi#125

I'm now confused: Are you breaking because of the deprecation warnings or because of "reference target not found" in the first comment above? Or both?

Ah, not really. I was redirected to this issue from #19850 . I specifically speaking about the MatplotlibDeprecationWarning. I don't know what the "reference target not found" issue is about but I think @nstarman found a fix.

Originally it was both, but we monkey-patched a solution to the "reference target not found" error by editing the matplotlib docstrings before subclassing Polygon (https://github.com/astropy/astropy/pull/11466/files, but PR is incorrectly named for what it solves).

It is presumably still an error if the monkey-patch is removed.

In the dev call today, we decided to replace the types (specifically CapStyle) by plain references, i.e.

s : `.CapStyle` or %(CapStyle)s

to

s : CapStyle_ or %(CapStyle)s

These should be resolved via intersphinx so that the monkey-patching becomes obsolete.

The deprecation warning is a separate topic, I'll reopen #19850.

@nstarman , suggestion from #19850 (comment) is a no-go, so I think the monkeypatch is there to stay until astropy can bump minversion of matplotlib to the version that has removed the deprecated attributes. FYI.

@pllim @nstarman AFAICT these two issues are completely unrelated.

The planned change here (#19839 (comment)) should make the monkey-patching obsolete.

I can't say I understand what's going on either. RTD passes with the monkey patch. Maybe the warning is red herring after all. 🤷🏻‍♀️