Nov 2, 2024 · Nov 2, 2024 · Jan 22, 2025 · Jan 22, 2025 · Jan 22, 2025 · Jan 22, 2025
diff --git a/doc/users/index.rst b/doc/users/index.rst

            explain/axes/index

    .. grid-item-card::
        :padding: 2

        .. toctree::
            :maxdepth: 2
            :includehidden:

            explain/plotting/index


    .. grid-item-card::
        :padding: 2
diff --git a/galleries/examples/images_contours_and_fields/contour_demo.py b/galleries/examples/images_contours_and_fields/contour_demo.py
 """
 .. _contour_demo:

 ============
 Contour Demo
 ============
diff --git a/galleries/examples/images_contours_and_fields/contourf_demo.py b/galleries/examples/images_contours_and_fields/contourf_demo.py
 """
 .. _contourf_demo:
 =============
 Contourf demo
 =============
diff --git a/galleries/examples/images_contours_and_fields/contourf_log.py b/galleries/examples/images_contours_and_fields/contourf_log.py
 """
 .. _contourf_log:

 ============================
 Contourf and log color scale
 ============================
diff --git a/galleries/examples/images_contours_and_fields/image_antialiasing.py b/galleries/examples/images_contours_and_fields/image_antialiasing.py
 """
 .. _image_antialiasing:

 .. _image_resampling:

 ================
 Image resampling
 ================
diff --git a/galleries/examples/images_contours_and_fields/image_demo.py b/galleries/examples/images_contours_and_fields/image_demo.py
 """
 .. _image_demo:

 ========================
 Many ways to plot images
 ========================
diff --git a/galleries/examples/images_contours_and_fields/pcolor_demo.py b/galleries/examples/images_contours_and_fields/pcolor_demo.py
 """
 .. _pcolor_demo:

 =============
 pcolor images
 =============
diff --git a/galleries/examples/images_contours_and_fields/pcolormesh_grids.py b/galleries/examples/images_contours_and_fields/pcolormesh_grids.py
 """
 .. _pcolormesh_grids:

 ============================
 pcolormesh grids and shading
 ============================
diff --git a/galleries/examples/images_contours_and_fields/plot_streamplot.py b/galleries/examples/images_contours_and_fields/plot_streamplot.py
 """
 .. _plot_streamplot:

 ==========
 Streamplot
 ==========
diff --git a/galleries/examples/images_contours_and_fields/tricontour_demo.py b/galleries/examples/images_contours_and_fields/tricontour_demo.py
 """
 .. _tricontour_demo:

 ===============
 Tricontour Demo
 ===============
diff --git a/galleries/examples/images_contours_and_fields/tricontour_smooth_delaunay.py b/galleries/examples/images_contours_and_fields/tricontour_smooth_delaunay.py
 """
 .. _tricontour_smooth_delaunay:

 ==========================
 Tricontour Smooth Delaunay
 ==========================
diff --git a/galleries/examples/images_contours_and_fields/tricontour_smooth_user.py b/galleries/examples/images_contours_and_fields/tricontour_smooth_user.py
 """
 .. _tricontour_smooth_user:

 ======================
 Tricontour Smooth User
 ======================
diff --git a/galleries/examples/images_contours_and_fields/tripcolor_demo.py b/galleries/examples/images_contours_and_fields/tripcolor_demo.py
 """
 .. _tripcolor_demo:

 ==============
 Tripcolor Demo
 ==============
diff --git a/galleries/examples/images_contours_and_fields/triplot_demo.py b/galleries/examples/images_contours_and_fields/triplot_demo.py
 """
 .. _triplot_demo:

 ============
 Triplot Demo
 ============
diff --git a/galleries/examples/lines_bars_and_markers/categorical_variables.py b/galleries/examples/lines_bars_and_markers/categorical_variables.py
 """
 .. _categorical_variables:

 ==============================
 Plotting categorical variables
 ==============================
diff --git a/galleries/examples/lines_bars_and_markers/eventplot_demo.py b/galleries/examples/lines_bars_and_markers/eventplot_demo.py
 """
 .. _eventplot_demo:

 ==============
 Eventplot demo
 ==============
diff --git a/galleries/examples/lines_bars_and_markers/fill_between_demo.py b/galleries/examples/lines_bars_and_markers/fill_between_demo.py
 """
 .. _fill_between_demo:

 ===============================
 Fill the area between two lines
 ===============================
diff --git a/galleries/examples/lines_bars_and_markers/step_demo.py b/galleries/examples/lines_bars_and_markers/step_demo.py
 """
 .. _step_demo:

 =========
 Step Demo
 =========
diff --git a/galleries/examples/mplot3d/bars3d.py b/galleries/examples/mplot3d/bars3d.py
 """
 .. _bars3d:

 ========================================
 Create 2D bar graphs in different planes
 ========================================
diff --git a/galleries/examples/mplot3d/box3d.py b/galleries/examples/mplot3d/box3d.py
 """
 .. _box3d:

 ===================
 3D box surface plot
 ===================
diff --git a/galleries/examples/mplot3d/custom_shaded_3d_surface.py b/galleries/examples/mplot3d/custom_shaded_3d_surface.py
 """
 .. _custom_shaded_3d_surface:

 =======================================
 Custom hillshading in a 3D surface plot
 =======================================
diff --git a/galleries/examples/mplot3d/intersecting_planes.py b/galleries/examples/mplot3d/intersecting_planes.py
 """
 .. _intersecting_planes:

 ===================
 Intersecting planes
 ===================
diff --git a/galleries/examples/mplot3d/quiver3d.py b/galleries/examples/mplot3d/quiver3d.py
 """
 .. _quiver3d:

 ==============
 3D quiver plot
 ==============
diff --git a/galleries/examples/mplot3d/stem3d_demo.py b/galleries/examples/mplot3d/stem3d_demo.py
 """
 .. _stem3d_demo:

 =======
 3D stem
 =======
diff --git a/galleries/examples/mplot3d/surface3d.py b/galleries/examples/mplot3d/surface3d.py
 """
 .. _surface3d:

 =====================
 3D surface (colormap)
 =====================
diff --git a/galleries/examples/mplot3d/surface3d_2.py b/galleries/examples/mplot3d/surface3d_2.py
 """
 .. _surface3d_2:

 ========================
 3D surface (solid color)
 ========================
diff --git a/galleries/examples/mplot3d/surface3d_3.py b/galleries/examples/mplot3d/surface3d_3.py
 """
 .. _surface3d_3:

 =========================
 3D surface (checkerboard)
 =========================
diff --git a/galleries/examples/mplot3d/trisurf3d.py b/galleries/examples/mplot3d/trisurf3d.py
 """
 .. _trisurf3d:

 ======================
 Triangular 3D surfaces
 ======================
diff --git a/galleries/examples/mplot3d/trisurf3d_2.py b/galleries/examples/mplot3d/trisurf3d_2.py
 """
 .. _trisurf3d_2:

 ===========================
 More triangular 3D surfaces
 ===========================
diff --git a/galleries/examples/statistics/boxplot.py b/galleries/examples/statistics/boxplot.py
 """
 .. _boxplot_artists:

 =================================
 Artist customization in box plots
 =================================
diff --git a/galleries/examples/statistics/boxplot_color.py b/galleries/examples/statistics/boxplot_color.py
 """
 .. _boxplot_color:

 =================================
 Box plots with custom fill colors
 =================================
diff --git a/galleries/examples/statistics/boxplot_demo.py b/galleries/examples/statistics/boxplot_demo.py
 """
 .. _boxplot_demo:

 ========
 Boxplots
 ========
diff --git a/galleries/examples/statistics/boxplot_vs_violin.py b/galleries/examples/statistics/boxplot_vs_violin.py
 """
 .. _boxplot_vs_violin:

 ===================================
 Box plot vs. violin plot comparison
 ===================================
diff --git a/galleries/examples/statistics/customized_violin.py b/galleries/examples/statistics/customized_violin.py
 """
 .. _customized_violin:

 =========================
 Violin plot customization
 =========================
diff --git a/galleries/examples/statistics/hexbin_demo.py b/galleries/examples/statistics/hexbin_demo.py
 """
 .. _hexbin_demo:

 =====================
 Hexagonal binned plot
 =====================
diff --git a/galleries/examples/statistics/histogram_histtypes.py b/galleries/examples/statistics/histogram_histtypes.py
 """
 .. _histogram_histtypes:

 ================================================================
 Demo of the histogram function's different ``histtype`` settings
 ================================================================
diff --git a/galleries/examples/statistics/histogram_multihist.py b/galleries/examples/statistics/histogram_multihist.py
 """
 .. _histogram_multihist:

 =====================================================
 The histogram (hist) function with multiple data sets
 =====================================================
diff --git a/galleries/examples/statistics/histogram_normalization.py b/galleries/examples/statistics/histogram_normalization.py
 """
 .. redirect-from:: /gallery/statistics/histogram_features
 .. _histogram_normalization:

 ===================================
 Histogram bins, density, and weight
diff --git a/galleries/examples/statistics/violinplot.py b/galleries/examples/statistics/violinplot.py
 """
 .. _violinplot:

 ==================
 Violin plot basics
 ==================
diff --git a/galleries/plot_types/3D/bar3d_simple.py b/galleries/plot_types/3D/bar3d_simple.py
 """
 .. _bar3d_simple:

 ==========================
 bar3d(x, y, z, dx, dy, dz)
 ==========================
diff --git a/galleries/plot_types/3D/surface3d_simple.py b/galleries/plot_types/3D/surface3d_simple.py
 """
 .. _surface3d_simple:

 =====================
 plot_surface(X, Y, Z)
 =====================
diff --git a/galleries/plot_types/3D/trisurf3d_simple.py b/galleries/plot_types/3D/trisurf3d_simple.py
 """
 .. _trisurf3d_simple:

 =====================
 plot_trisurf(x, y, z)
 =====================
diff --git a/galleries/plot_types/arrays/pcolormesh.py b/galleries/plot_types/arrays/pcolormesh.py
 """
 .. _pcolormesh:

 ===================
 pcolormesh(X, Y, Z)
 ===================

 Create a pseudocolor plot with a non-regular rectangular grid.

 `~.axes.Axes.pcolormesh` is more flexible than `~.axes.Axes.imshow` in that
diff --git a/galleries/users_explain/artists/index.rst b/galleries/users_explain/artists/index.rst
 .. _users-guide-artists:

 +++++++
 Artists
 +++++++
diff --git a/galleries/users_explain/axes/index.rst b/galleries/users_explain/axes/index.rst
 .. _users_guide_axes:

 +++++++++++++++++
 Axes and subplots
 +++++++++++++++++
Original file line number	Diff line number	Diff line change
Expand Up		@@ -42,6 +42,15 @@ Using Matplotlib

		explain/axes/index

		.. grid-item-card::
		:padding: 2

		.. toctree::
		:maxdepth: 2
		:includehidden:

		explain/plotting/index


		.. grid-item-card::
		:padding: 2
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -1,4 +1,6 @@
		"""
		.. _contour_demo:
Copy link Member timhoffmJan 22, 2025 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. Is there a reason you introduce labels to a lot of examples? Generally, we've been referencing examples via the doc:doc:`/gallery/images_contours_and_fiels/contour_demo`. See alsohttps://matplotlib.org/devdocs/devel/document.html#refer-to-other-documents-and-sections. Copy link MemberAuthor jklymakJan 22, 2025 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. Because if we have to re-arrange things all these hard links break, whereas labeled references do not break. Copy link Member timhoffmJan 22, 2025 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. IMHO this is a case of YAGNI. We are quite conservative on the structure because it translates to public URLs. And if we really want to change, that’s a quite easy search&replace, which we need to anyway, because our current way of referencing examples is predominantly doc based. This makes the PR look more complicated and I’ve some reservations whether it’s actually better to reference examples using labels. Copy link Member story645Jan 22, 2025 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. I don't mind it b/c we've done some thrashing on the galleries, but I think it might make both discussions easier if it was spun out into a separate PR Copy link MemberAuthor jklymakJan 22, 2025 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. IMHO this is a case of YAGNI. We are quite conservative on the structure because it translates to public URLs. And if we really want to change, that’s a quite easy search&replace, which we need to anyway, because our current way of referencing examples is predominantly doc based. This was a huge barrier to making doc changes 5 or so years ago. Since then we introduced the redirect mechanism which has allowed things to be moved. It is likely true that our predominant way of referencing things is`:doc:` based, I'd argue`:ref:` is much more flexible. Certainly`:ref:` is used in many places as well. Regardless, I don't think this really affects this PR. I made zero substantive changes to any of the other files - I just added the reference label. I also didn't change any`:doc:` calls elsewhere. Copy link Member timhoffmJan 23, 2025• edited Loading Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. It is likely true that our predominant way of referencing things is :doc: based To give a number: 7 examples have labels. but we have 150 :doc: references. Regardless, I don't think this really affects this PR. I beg to differ: Substantially introducing label-based referencing for examples is a new paradigm, which I don't want to introduce as a side-effect. I'm not going here into the pros and cons, even tough I have opinions. This deserves a dedicated discussion. It would be fine if you simultaneously have open an issue on this. It further bloats a nontheless giant PR to 51 files and >1500 lines. I simply refuse to review this size of PR unless there are strong arguments that it cannot be splittedand the huge PR is sub-structured into reasonable commits. So the effect is at least I'm not looking at this, which is fine as long as you find other reviewers. I'm just giving my perspective. Others would have to comment on why they haven't reviewed. Copy link MemberAuthor jklymakJan 23, 2025 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. Substantially introducing label-based referencing for examples is a new paradigm, which I don't want to introduce as a side-effect. Again, this isn't new, or just being introduced now - we have had label-based referencing for as long as I have been contributing. All this PR does is add labels, it doesn't change any existing references. If I put in a stand-alone PR with just the labels, that is all it would be - a bunch of labels not used anywhere yet. I can certainly do that if you like, but I'm not sure what the point is. To give a number: 7 examples have labels. but we have 150 :doc: references. An aside, for sure, but`:ref:` is used 738 times in our docs, and a quick skim indicates that they are all label based references to elsewhere in the docs.`:doc:` is used 291 times. Perhaps you are making a distinction between the gallery and the rest of the docs? Copy link Member story645Jan 23, 2025• edited Loading Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. @jklymak do you have a strong objection to splitting off the labeling PR from the plotting guide PR? I tend to review docs on my phone so it's a lot to scroll past, and as the back and forth with Tim is showing there's a whole separate conversation to be had about labeling. If I put in a stand-alone PR with just the labels, that is all it would be - a bunch of labels not used anywhere yet That's fine, folks do staged PRs all the time. Just say it's for this PR. Or put adding the labels in a separate first commit so reviewers can filter it out. Copy link MemberAuthor jklymakJan 23, 2025 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. I could do both those things if it makes things easier. Copy link MemberAuthor jklymakJan 23, 2025 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. Done

		============
		Contour Demo
		============
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -1,4 +1,5 @@
		"""
		.. _contourf_demo:
		=============
		Contourf demo
		=============
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -1,4 +1,6 @@
		"""
		.. _contourf_log:

		============================
		Contourf and log color scale
		============================
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -1,4 +1,8 @@
		"""
		.. _image_antialiasing:

		.. _image_resampling:

		================
		Image resampling
		================
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -1,4 +1,6 @@
		"""
		.. _image_demo:

		========================
		Many ways to plot images
		========================
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -1,4 +1,6 @@
		"""
		.. _pcolor_demo:

		=============
		pcolor images
		=============
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -1,4 +1,6 @@
		"""
		.. _pcolormesh_grids:

		============================
		pcolormesh grids and shading
		============================
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -1,4 +1,6 @@
		"""
		.. _plot_streamplot:

		==========
		Streamplot
		==========
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -1,4 +1,6 @@
		"""
		.. _tricontour_demo:

		===============
		Tricontour Demo
		===============
Expand Down