Repository navigation
Subclasses of Polygon with numpydoc xref throws error b/c of CapStyle, JoinStyle #19839
Description
Problem
The sphinx links to CapStyle and JoinStyle in v3.4.0 are relative to the file, so a subclass of matplotlib.patches.Patch in a package with numpydoc xref (https://numpydoc.readthedocs.io/en/latest/install.html) turned on cannot link to the objects and errors with.
WARNING: py:obj reference target not found: CapStyle
WARNING: py:obj reference target not found: JoinStyle
https://matplotlib.org/stable/api/_as_gen/matplotlib.patches.Patch.html#matplotlib.patches.Patch.set_capstyle
https://matplotlib.org/stable/api/_as_gen/matplotlib.patches.Patch.html#matplotlib.patches.Patch.set_joinstyle
@docstring.interpd
def set_capstyle(self, s):
"""
Set the `.CapStyle`.
Parameters
----------
s : `.CapStyle` or %(CapStyle)s
"""
cs = CapStyle(s)
self._capstyle = cs
self.stale = True
Edit:
The problem also appears to involve Patches.__init__. I can monkey-patch a fix with
Polygon.__init__.__doc__ = Polygon.__init__.__doc__.replace(
"`.CapStyle`", "``matplotlib._enums.CapStyle``")
Polygon.__init__.__doc__ = Polygon.__init__.__doc__.replace(
"`.JoinStyle`", "``matplotlib._enums.JoinStyle``")
Polygon.set_capstyle.__doc__ = Polygon.set_capstyle.__doc__.replace(
"`.CapStyle`", "``matplotlib._enums.CapStyle``")
Polygon.set_joinstyle.__doc__ = Polygon.set_joinstyle.__doc__.replace(
"`.JoinStyle`", "``matplotlib._enums.JoinStyle``")
Suggested Improvement
- This line could be be changed to say
@docstring.interpd
def set_capstyle(self, s):
"""
Set the `~matplotlib._enums.CapStyle`.
Parameters
----------
s : `~matplotlib._enums.CapStyle` or %(CapStyle)s
"""
cs = CapStyle(s)
self._capstyle = cs
self.stale = True
Matplotlib version
- Operating system: Big Sur & Ubuntu
- Matplotlib version 3.4.0
- Matplotlib documentation version (is listed under the logo): 3.4.0
Activity
[-]Subclasses Polygon with numpydoc xref throws error b/c of CapStyle, JoinStyle[/-][+]Subclasses of Polygon with numpydoc xref throws error b/c of CapStyle, JoinStyle[/+]jklymak commentedon Mar 31, 2021
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?
timhoffm commentedon Mar 31, 2021
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.
nstarman commentedon Apr 1, 2021
As far as I can tell, the xref issue stems from the fact that references to
CapStyleandJoinStyleare relative paths, not absolute. I've found for other references in Astropy that changing`.object`to`~package.subpackage.object`resolves the issueAvoid deprecation warning in wcsaxes doc
Avoid deprecation warning in wcsaxes doc
Avoid deprecation warning in wcsaxes doc
pllim commentedon Apr 3, 2021
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
anntzer commentedon Apr 3, 2021
I think this may be related to sphinx-doc/sphinx#6211 (which I basically opened based on my experience with matplotlib)?
anntzer commentedon Apr 8, 2021
I am bit confused why this specific dotted reference breaks your build whereas a lot of other dotted references (e.g.
.Transform) don't?pllim commentedon Apr 8, 2021
@anntzer , these are the warnings (it breaks because we have RTD set to fail on warning):
The code in
astropydoes not specifically have them, but rather a subclass inherited them. And then Sphinx tries to render docstring for inherited attributes. We also usesphinx-automodapiplugin to render it. So, it is really a perfect storm of a few things put together.References: astropy/astropy#11458 astropy/sphinx-automodapi#125
timhoffm commentedon Apr 8, 2021
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?
pllim commentedon Apr 8, 2021
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.23 remaining items
jklymak commentedon Oct 8, 2023
I can't tell from the above if this is still an issue. I would guess not, so I'll close, but feel free to request a re-open with the current state of things.
pllim commentedon Oct 8, 2023
We still have the hack in the code but no time to revisit.
jklymak commentedon Oct 8, 2023
Please open a new issue(s) if you still need help narrowing down the scope.