Problem

Our standard way to handle missing references is our missing_references extension, which specifies explicit error messages including line numbers inside missing_references.json.

This is cumbersome because docstring edits can change the line numbers, requiring to adapt the missing_references.json.

Suggested improvement

I just found out, that one can suppress references by prefixing with an exclamation mark. This seems undocumented but is used inside the sphinx docs, e.g. :class:`!MyClass` . I've opened an issue on that: sphinx-doc/sphinx#12940.

If this is intended as a public feature on the sphinx side, I propose to switch to it and dump our missing references. This has several advantages:

• The missing info is inlined, so that we can see in the sources whether the link will works or not.
• We don't have problems with line number changes anymore.
• When references vanish, e.g. by removal after deprecation, we don't have to change old references, e.g. in changelog to a literal role, but can simply prefix them with the exclamation mark.
• It's still straight forward to get an overview of missing references by searching for `!

Sprint task

For the following references, add a ! in front, e.g. :class:`MyClass` -> :class:`!MyClass`

When the reference is inside a method docstring, the method is listed in parenthesis, e.g. :class:`MyClass` (method)

To avoid merge conflicts, please choose 1 file to work on at a time and note it here

doc/tutorials/

• galleries/tutorials/artists.py: Updates the galleries/tutorials/artists.py file in response to issue #28920 #29080
  • :attr:matplotlib.axes.Axes.patch
  • :attr:matplotlib.figure.Figure.patch
  • :class:matplotlib.backend_bases.FigureCanvas
  • :class:matplotlib.backend_bases.Renderer
  • :attr:matplotlib.figure.Figure.transFigure
  • :attr:matplotlib.axes.Axes.patches
  • :attr:matplotlib.axes.Axes.xaxis
  • :attr:matplotlib.axes.Axes.yaxis

doc/users/

#29086

• galleries/users/explain/figure/event_handling.py:
  • :obj:Rectangle.contains
  • :obj:Line2D.pick
• galleries/users/explain/figure/interactive.py:
  • :obj:ipykernel.pylab.backend_inline
• galleries/users/explain/figure/interactive_guide.py:
  • :obj:Artist.stale_callback
  • :obj:Figure.stale_callback
  • :meth:IPython.terminal.interactiveshell.TerminalInteractiveShell.inputhook

doc/api/

• doc/api/toolkits/axisartist.rst:
  • :class:mpl_toolkits.axisartist.Axes
• doc/api/toolkits/mplot3d.rst:
  • :attr:mpl_toolkits.mplot3d.axis3d._axinfo

lib/matplotlib/

• lib/matplotlib/axes/_axes.py:
  • :meth:matplotlib.collections._CollectionWithSizes.set_sizes (matplotlib.axes._axes.Axes.barbs)
  • :obj:ax.transAxes (matplotlib.axes._axes.Axes.inset_axes)
  • :meth:matplotlib.collections._MeshData.set_array (matplotlib.axes._axes.Axes.pcolormesh)
  • :obj:kde.factor (matplotlib.axes._axes.Axes.violinplot)
• lib/matplotlib/axes/_base.py:
  • :obj:fmt_xdata (matplotlib.axes._base._AxesBase.format_xdata)
  • :obj:fmt_ydata (matplotlib.axes._base._AxesBase.format_ydata)
• lib/matplotlib/backend_bases.py:
  • :obj:Timer (matplotlib.backend_bases.FigureCanvasBase.new_timer)
  • :obj:_iter_collection_raw_paths (matplotlib.backend_bases.RendererBase.draw_path_collection)
  • :obj:_iter_collection (matplotlib.backend_bases.RendererBase.draw_path_collection)
  • :class:matplotlib.backend_bases._Backend (matplotlib.backend_bases.ShowBase)
  • :obj:ToolContainer (matplotlib.backend_bases.ToolContainerBase.remove_toolitem)
• lib/matplotlib/backend_tools.py:
  • :obj:toggled (matplotlib.backend_tools.AxisScaleBase.disable)
• lib/matplotlib/backends/backend_agg.py:
  • :obj:draw_image (matplotlib.backends.backend_agg.RendererAgg.option_scale_image)
• lib/matplotlib/backends/backend_cairo.py:
  • :obj:option_scale_image (matplotlib.backends.backend_cairo.RendererCairo.draw_image)
• lib/matplotlib/backends/backend_pdf.py:
  • :class:matplotlib.backends._backend_pdf_ps.RendererPDFPSBase (matplotlib.backends.backend_pdf.RendererPdf)
• lib/matplotlib/backends/backend_tkagg.py:
  • :class:matplotlib.backends._backend_tk.FigureCanvasTk (matplotlib.backends.backend_tkagg.FigureCanvasTkAgg)
• lib/matplotlib/colorbar.py:
  • :attr:lines (matplotlib.colorbar.Colorbar.add_lines)
• lib/matplotlib/dviread.py:
  • :obj:_read (matplotlib.dviread.Vf)
• lib/matplotlib/image.py:
  • :obj:can_composite (matplotlib.image.composite_images)
  • :obj:make_image (matplotlib.image.composite_images)
• lib/matplotlib/mlab.py:
  • :obj:kde.covariance_factor (matplotlib.mlab.GaussianKDE)
• lib/matplotlib/patches.py:
  • :class:matplotlib.patches._Style (matplotlib.patches.ArrowStyle)
  • :class:matplotlib.patches.ArrowStyle._Curve (matplotlib.patches.ArrowStyle.BarAB)
  • :class:matplotlib.patches.ArrowStyle._Base (matplotlib.patches.ArrowStyle.Fancy)
  • :class:matplotlib.patches.ConnectionStyle._Base (matplotlib.patches.ConnectionStyle.Angle3)
• lib/matplotlib/patheffects.py:
  • :meth:AbstractPathEffect._update_gc (matplotlib.patheffects.SimpleLineShadow)
• lib/matplotlib/projections/geo.py:
  • :class:matplotlib.projections.geo._GeoTransform (matplotlib.projections.geo.AitoffAxes.AitoffTransform)
  • :attr:input_dims (matplotlib.projections.geo.AitoffAxes.AitoffTransform.transform_non_affine)
  • :attr:output_dims (matplotlib.projections.geo.AitoffAxes.AitoffTransform.transform_non_affine)
• lib/matplotlib/pyplot.py:
  • :obj:Image (matplotlib.pyplot.gci)
• lib/matplotlib/quiver.py:
  • :meth:_find_tails (matplotlib.quiver.Barbs)
  • :meth:_make_barbs (matplotlib.quiver.Barbs)
• lib/matplotlib/scale.py:
  • :attr:name (matplotlib.scale.ScaleBase)
• lib/matplotlib/testing/compare.py:
  • :obj:converter (matplotlib.testing.compare.compare_images)
• lib/matplotlib/transforms.py:
  • :attr:height (matplotlib.transforms.Bbox.bounds)
  • :attr:width (matplotlib.transforms.Bbox.bounds)
  • :attr:min (matplotlib.transforms.Bbox.p0)
  • :attr:max (matplotlib.transforms.Bbox.p1)
  • :attr:xmin (matplotlib.transforms.Bbox.x0)
  • :attr:xmax (matplotlib.transforms.Bbox.x1)
  • :attr:ymin (matplotlib.transforms.Bbox.y0)
  • :attr:ymax (matplotlib.transforms.Bbox.y1)
  • :class:matplotlib.transforms._BlendedMixin (matplotlib.transforms.BlendedAffine2D)
• lib/matplotlib/tri/_trirefine.py:
  • :attr:triangulation (matplotlib.tri._trirefine.UniformTriRefiner.refine_triangulation)
• lib/matplotlib/widgets.py:
  • :obj:active (matplotlib.widgets.AxesWidget)
  • :attr:eventson (matplotlib.widgets.CheckButtons.set_active)
  • :class:matplotlib.widgets._SelectorWidget (matplotlib.widgets.LassoSelector)

lib/mpl_toolkits/

• lib/mpl_toolkits/axes_grid1/anchored_artists.py:
  • :attr:matplotlib.axes.Axes.transData (mpl_toolkits.axes_grid1.anchored_artists.AnchoredAuxTransformBox)
  • :attr:matplotlib.axes.Axes.transAxes (mpl_toolkits.axes_grid1.anchored_artists.AnchoredDirectionArrows)
• lib/mpl_toolkits/axes_grid1/axes_grid.py:
  • :attr:cbar_axes (mpl_toolkits.axes_grid1.axes_grid.ImageGrid)
  • :obj:Size.from_any (mpl_toolkits.axes_grid1.axes_grid.ImageGrid)
• lib/mpl_toolkits/axes_grid1/axes_size.py:
  • :obj:get_size (mpl_toolkits.axes_grid1.axes_size)
  • :class:mpl_toolkits.axes_grid1.axes_size._Base (mpl_toolkits.axes_grid1.axes_size.Add)
• lib/mpl_toolkits/axisartist/axis_artist.py:
  • :obj:mpl_toolkits.axislines.Axes (mpl_toolkits.axisartist.axis_artist)
• lib/mpl_toolkits/axisartist/axisline_style.py:
  • :class:mpl_toolkits.axisartist.axisline_style.AxislineStyle._Base (mpl_toolkits.axisartist.axisline_style.AxislineStyle.SimpleArrow)
• lib/mpl_toolkits/mplot3d/axes3d.py:
  • :attr:fmt_zdata (mpl_toolkits.mplot3d.axes3d.Axes3D.format_zdata)