Workaround to prevent "reference target not found" errors in doc builds

timhoffm · timhoffm · commit d2654be18352 · 2021-07-06T00:03:32.000+02:00
This introduces a known blacklist of currently non-linkable items.
diff --git a/doc/api/axis_api.rst b/doc/api/axis_api.rst
@@ -181,6 +181,7 @@ XAxis Specific
    XAxis.get_text_heights
    XAxis.get_ticks_position
    XAxis.set_ticks_position
+   XAxis.set_label_position
    XAxis.tick_bottom
    XAxis.tick_top
 
@@ -197,6 +198,7 @@ YAxis Specific
    YAxis.get_ticks_position
    YAxis.set_offset_position
    YAxis.set_ticks_position
+   YAxis.set_label_position
    YAxis.tick_left
    YAxis.tick_right
 
@@ -264,4 +266,5 @@ specify a matching series of labels.  Calling ``set_ticks`` makes a
    Tick.set_label1
    Tick.set_label2
    Tick.set_pad
+   Tick.set_url
    Tick.update_position
diff --git a/lib/matplotlib/artist.py b/lib/matplotlib/artist.py
@@ -1444,6 +1444,46 @@ def aliased_name(self, s):
         aliases = ''.join(' or %s' % x for x in sorted(self.aliasd.get(s, [])))
         return s + aliases
 
+    _NOT_LINKABLE = {
+        # A set of property setter methods that are not available in our
+        # current docs. This is a workaround used to prevent trying to link
+        # these setters which would lead to "target reference not found"
+        # warnings during doc build.
+        'matplotlib.image._ImageBase.set_alpha',
+        'matplotlib.image._ImageBase.set_array',
+        'matplotlib.image._ImageBase.set_data',
+        'matplotlib.image._ImageBase.set_filternorm',
+        'matplotlib.image._ImageBase.set_filterrad',
+        'matplotlib.image._ImageBase.set_interpolation',
+        'matplotlib.image._ImageBase.set_resample',
+        'matplotlib.image._ImageBase.set_alpha',
+        'matplotlib.image._ImageBase.set_array',
+        'matplotlib.image._ImageBase.set_data',
+        'matplotlib.image._ImageBase.set_filternorm',
+        'matplotlib.image._ImageBase.set_filterrad',
+        'matplotlib.image._ImageBase.set_interpolation',
+        'matplotlib.image._ImageBase.set_resample',
+        'matplotlib.image._ImageBase.set_alpha',
+        'matplotlib.image._ImageBase.set_array',
+        'matplotlib.image._ImageBase.set_filternorm',
+        'matplotlib.image._ImageBase.set_filterrad',
+        'matplotlib.image._ImageBase.set_interpolation',
+        'matplotlib.image._ImageBase.set_resample',
+        'matplotlib.image._ImageBase.set_alpha',
+        'matplotlib.image._ImageBase.set_array',
+        'matplotlib.image._ImageBase.set_filternorm',
+        'matplotlib.image._ImageBase.set_filterrad',
+        'matplotlib.image._ImageBase.set_resample',
+        'matplotlib.image._ImageBase.set_alpha',
+        'matplotlib.image._ImageBase.set_array',
+        'matplotlib.image._ImageBase.set_filternorm',
+        'matplotlib.image._ImageBase.set_filterrad',
+        'matplotlib.image._ImageBase.set_interpolation',
+        'matplotlib.image._ImageBase.set_resample',
+        'matplotlib.text._AnnotationBase.set_annotation_clip',
+        'matplotlib.text._AnnotationBase.set_annotation_clip',
+    }
+
     def aliased_name_rest(self, s, target):
         """
         Return 'PROPNAME or alias' if *s* has an alias, else return 'PROPNAME',
@@ -1453,6 +1493,10 @@ def aliased_name_rest(self, s, target):
         alias, return 'markerfacecolor or mfc' and for the transform
         property, which does not, return 'transform'.
         """
+        # workaround to prevent "reference target not found"
+        if target in self._NOT_LINKABLE:
+            return f'``{s}``'
+
         aliases = ''.join(' or %s' % x for x in sorted(self.aliasd.get(s, [])))
         return ':meth:`%s <%s>`%s' % (s, target, aliases)
 
@@ -1506,6 +1550,8 @@ def pprint_setters_rest(self, prop=None, leadingspace=4):
                     break
             else:  # No docstring available.
                 method = getattr(self.o, f"set_{prop}")
+            if method.__qualname__.startswith('_'):
+                print(method.__qualname__)
             prop_and_qualnames.append(
                 (prop, f"{method.__module__}.{method.__qualname__}"))
 
@@ -1713,7 +1759,7 @@ def kwdoc(artist):
     """
     ai = ArtistInspector(artist)
     return ('\n'.join(ai.pprint_setters_rest(leadingspace=4))
-            if mpl.rcParams['docstring.hardcopy'] else
+            if mpl.rcParams['docstring.hardcopy'] or True else
             'Properties:\n' + '\n'.join(ai.pprint_setters(leadingspace=4)))
 
 # We defer this to the end of them module, because it needs ArtistInspector
