Repository navigation
[Doc]: Suppress missing references through a ! prefix instead of missing_references extension. #28920
Description
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.pyfile 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
- :attr:
doc/users/
- galleries/users/explain/figure/event_handling.py:
- :obj:
Rectangle.contains - :obj:
Line2D.pick
- :obj:
- galleries/users/explain/figure/interactive.py:
- :obj:
ipykernel.pylab.backend_inline
- :obj:
- galleries/users/explain/figure/interactive_guide.py:
- :obj:
Artist.stale_callback - :obj:
Figure.stale_callback - :meth:
IPython.terminal.interactiveshell.TerminalInteractiveShell.inputhook
- :obj:
doc/api/
- doc/api/toolkits/axisartist.rst:
- :class:
mpl_toolkits.axisartist.Axes
- :class:
- doc/api/toolkits/mplot3d.rst:
- :attr:
mpl_toolkits.mplot3d.axis3d._axinfo
- :attr:
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)
- :meth:
- lib/matplotlib/axes/_base.py:
- :obj:
fmt_xdata(matplotlib.axes._base._AxesBase.format_xdata) - :obj:
fmt_ydata(matplotlib.axes._base._AxesBase.format_ydata)
- :obj:
- 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)
- :obj:
- lib/matplotlib/backend_tools.py:
- :obj:
toggled(matplotlib.backend_tools.AxisScaleBase.disable)
- :obj:
- lib/matplotlib/backends/backend_agg.py:
- :obj:
draw_image(matplotlib.backends.backend_agg.RendererAgg.option_scale_image)
- :obj:
- lib/matplotlib/backends/backend_cairo.py:
- :obj:
option_scale_image(matplotlib.backends.backend_cairo.RendererCairo.draw_image)
- :obj:
- lib/matplotlib/backends/backend_pdf.py:
- :class:
matplotlib.backends._backend_pdf_ps.RendererPDFPSBase(matplotlib.backends.backend_pdf.RendererPdf)
- :class:
- lib/matplotlib/backends/backend_tkagg.py:
- :class:
matplotlib.backends._backend_tk.FigureCanvasTk(matplotlib.backends.backend_tkagg.FigureCanvasTkAgg)
- :class:
- lib/matplotlib/colorbar.py:
- :attr:
lines(matplotlib.colorbar.Colorbar.add_lines)
- :attr:
- lib/matplotlib/dviread.py:
- :obj:
_read(matplotlib.dviread.Vf)
- :obj:
- lib/matplotlib/image.py:
- :obj:
can_composite(matplotlib.image.composite_images) - :obj:
make_image(matplotlib.image.composite_images)
- :obj:
- lib/matplotlib/mlab.py:
- :obj:
kde.covariance_factor(matplotlib.mlab.GaussianKDE)
- :obj:
- 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)
- :class:
- lib/matplotlib/patheffects.py:
- :meth:
AbstractPathEffect._update_gc(matplotlib.patheffects.SimpleLineShadow)
- :meth:
- 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)
- :class:
- lib/matplotlib/pyplot.py:
- :obj:
Image(matplotlib.pyplot.gci)
- :obj:
- lib/matplotlib/quiver.py:
- :meth:
_find_tails(matplotlib.quiver.Barbs) - :meth:
_make_barbs(matplotlib.quiver.Barbs)
- :meth:
- lib/matplotlib/scale.py:
- :attr:
name(matplotlib.scale.ScaleBase)
- :attr:
- lib/matplotlib/testing/compare.py:
- :obj:
converter(matplotlib.testing.compare.compare_images)
- :obj:
- 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)
- :attr:
- lib/matplotlib/tri/_trirefine.py:
- :attr:
triangulation(matplotlib.tri._trirefine.UniformTriRefiner.refine_triangulation)
- :attr:
- lib/matplotlib/widgets.py:
- :obj:
active(matplotlib.widgets.AxesWidget) - :attr:
eventson(matplotlib.widgets.CheckButtons.set_active) - :class:
matplotlib.widgets._SelectorWidget(matplotlib.widgets.LassoSelector)
- :obj:
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)
- :attr:
- 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)
- :attr:
- 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)
- :obj:
- lib/mpl_toolkits/axisartist/axis_artist.py:
- :obj:
mpl_toolkits.axislines.Axes(mpl_toolkits.axisartist.axis_artist)
- :obj:
- lib/mpl_toolkits/axisartist/axisline_style.py:
- :class:
mpl_toolkits.axisartist.axisline_style.AxislineStyle._Base(mpl_toolkits.axisartist.axisline_style.AxislineStyle.SimpleArrow)
- :class:
- lib/mpl_toolkits/mplot3d/axes3d.py:
- :attr:
fmt_zdata(mpl_toolkits.mplot3d.axes3d.Axes3D.format_zdata)
- :attr:
Reacted by hannah and Ruth Comer
Activity
AA-Turner commentedon Oct 1, 2024
Quick reference (ha) to cross-referencing syntax:
A
AbhinRustagi commentedon Oct 9, 2024
@timhoffm I would be happy to work on this
timhoffm commentedon Oct 11, 2024
@AbhinRustagi thanks for the interest. So far, this is a proposal. I'd like to get feedback from other core devs before moving forward.
tacaswell commentedon Oct 11, 2024
I am 👍 on using this.
As a side note, how long at
!done this?timhoffm commentedon Oct 11, 2024
Since 2007: sphinx-doc/sphinx@b6024b9a (and it has been documented since 2008 sphinx-doc/sphinx@06dd99e1)
timhoffm commentedon Oct 11, 2024
@AbhinRustagi you are welcome to start working on this.
story645 commentedon Nov 4, 2024
Updated the above w/ all the entries in missing reference that seemed easily fixable. The rest of the entries I can't find in any docstring/doc and about half seem to be due to how the animation class is architectured, but I'll list them here for anyone who wants to take a stab at figuring out what's going on:
Animation
matplotlib.animation.ArtistAnimation.new_frame_seqmatplotlib.animation.ArtistAnimation.new_saved_frame_seqmatplotlib.animation.ArtistAnimation.pausematplotlib.animation.ArtistAnimation.resumematplotlib.animation.ArtistAnimation.savematplotlib.animation.ArtistAnimation.to_html5_videomatplotlib.animation.ArtistAnimation.to_jshtmlmatplotlib.animation.FFMpegFileWriter.bin_pathmatplotlib.animation.FFMpegFileWriter.finishmatplotlib.animation.FFMpegFileWriter.grab_framematplotlib.animation.FFMpegFileWriter.isAvailablematplotlib.animation.FFMpegFileWriter.savingmatplotlib.animation.FFMpegFileWriter.setupmatplotlib.animation.FFMpegWriter.bin_pathmatplotlib.animation.FFMpegWriter.finishmatplotlib.animation.FFMpegWriter.grab_framematplotlib.animation.FFMpegWriter.isAvailablematplotlib.animation.FFMpegWriter.savingmatplotlib.animation.FFMpegWriter.setupmatplotlib.animation.FFMpegWriter.frame_sizematplotlib.animation.FFMpegWriter.output_argsmatplotlib.animation.FFMpegWriter.supported_formatsmatplotlib.animation.FileMovieWriter.bin_pathmatplotlib.animation.FileMovieWriter.isAvailablematplotlib.animation.FileMovieWriter.savingmatplotlib.animation.HTMLWriter.bin_pathmatplotlib.animation.HTMLWriter.savingmatplotlib.animation.ImageMagickFileWriter.bin_pathmatplotlib.animation.ImageMagickFileWriter.finishmatplotlib.animation.ImageMagickFileWriter.grab_framematplotlib.animation.ImageMagickFileWriter.isAvailablematplotlib.animation.ImageMagickFileWriter.savingmatplotlib.animation.ImageMagickFileWriter.setupmatplotlib.animation.ImageMagickWriter.bin_pathmatplotlib.animation.ImageMagickWriter.finishmatplotlib.animation.ImageMagickWriter.grab_framematplotlib.animation.ImageMagickWriter.isAvailablematplotlib.animation.ImageMagickWriter.savingmatplotlib.animation.ImageMagickWriter.setupmatplotlib.animation.MovieWriter.savingmatplotlib.animation.PillowWriter.savingmatplotlib.animation.TimedAnimation.new_frame_seqmatplotlib.animation.TimedAnimation.new_saved_frame_seqmatplotlib.animation.TimedAnimation.pausematplotlib.animation.TimedAnimation.resumematplotlib.animation.TimedAnimation.savematplotlib.animation.TimedAnimation.to_html5_videomatplotlib.animation.TimedAnimation.to_jshtmlmatplotlib.animation.FFMpegFileWriter.frame_format(matplotlib.animation.FFMpegFileWriter.supported_formats)matplotlib.animation.FFMpegFileWriter.frame_size(matplotlib.animation.FFMpegFileWriter.supported_formats)matplotlib.animation.FFMpegFileWriter.output_args(matplotlib.animation.FFMpegFileWriter.supported_formats)matplotlib.animation.FileMovieWriter.frame_size(matplotlib.animation.FileMovieWriter.finish)matplotlib.animation.FileMovieWriter.supported_formats(matplotlib.animation.FileMovieWriter.finish)matplotlib.animation.FuncAnimation.pause(matplotlib.animation.FuncAnimation.new_frame_seq)matplotlib.animation.FuncAnimation.resume(matplotlib.animation.FuncAnimation.new_frame_seq)matplotlib.animation.FuncAnimation.save(matplotlib.animation.FuncAnimation.new_frame_seq)matplotlib.animation.FuncAnimation.to_html5_video(matplotlib.animation.FuncAnimation.new_frame_seq)matplotlib.animation.FuncAnimation.to_jshtml(matplotlib.animation.FuncAnimation.new_frame_seq)matplotlib.animation.HTMLWriter.frame_format(matplotlib.animation.HTMLWriter.finish)matplotlib.animation.HTMLWriter.frame_size(matplotlib.animation.HTMLWriter.finish)matplotlib.animation.ImageMagickFileWriter.frame_format(matplotlib.animation.ImageMagickFileWriter.input_names)matplotlib.animation.ImageMagickFileWriter.frame_size(matplotlib.animation.ImageMagickFileWriter.input_names)matplotlib.animation.ImageMagickWriter.frame_size(matplotlib.animation.ImageMagickWriter.input_names)matplotlib.animation.ImageMagickWriter.supported_formats(matplotlib.animation.ImageMagickWriter.input_names)matplotlib.animation.MovieWriter.frame_size(matplotlib.animation.MovieWriter.bin_path)matplotlib.animation.PillowWriter.frame_size(matplotlib.animation.PillowWriter.finish)doc/api (these seem to be part of an inheritance diagram?)
matplotlib.axes._base._AxesBasematplotlib.collections._CollectionWithSizesmatplotlib.collections._MeshDatamatplotlib.image._ImageBasematplotlib.text._AnnotationBasedoc/docstring of matplotlib.ft2font.PyCapsule.set_text/ <-this method doesn't exist in matplotlib
numpy.float64can't find in text
HashableList[_HT]mpl_toolkits.axes_grid1.parasite_axes.AxesHostAxesmpl_toolkits.axes_grid1.parasite_axes.AxesParasitempl_toolkits.axisartist.axisline_style._FancyAxislineStyle.FilledArrowmpl_toolkits.axisartist.axisline_style._FancyAxislineStyle.SimpleArrowmpl_toolkits.axisartist.axislines._FixedAxisArtistHelperBasempl_toolkits.axisartist.axislines._FloatingAxisArtistHelperBasempl_toolkits.axisartist.floating_axes.FloatingAxesHostAxesnumpy.uint8matplotlib.typing._HTfocardozom commentedon Nov 5, 2024
Hi! I'll work on the artists.py and doc/users/
Astro42 commentedon Nov 5, 2024
hi! I'll work on the axisartist.rst
Updates galleries/user_explain/figure/ files in response to issue mat…
Merge pull request #29080 from focardozom/main
Backport PR matplotlib#29080: Updates the `galleries/tutorials/artist…
Merge pull request #29140 from meeseeksmachine/auto-backport-of-pr-29…
timhoffm commentedon Feb 1, 2025
Semi-related #29560 fixes
_CollectionWithSizes.set_sizesreferences, which are injected through the"(SubClass:kwdoc)s"placeholder mechanism.timhoffm commentedon Dec 8, 2025
Closing as mostly solved. The remaining entries are mostly references to objects that are not documented via autodoc and therefore cannot be linked.