Deprecate draw_gouraud_triangle (matplotlib#23824)

* Deprecate draw_gouraud_triangle

* DOC: minor rewording

Co-authored-by: Elliott Sales de Andrade <quantum.analyst@gmail.com>

Co-authored-by: Thomas A Caswell <tcaswell@gmail.com>
Co-authored-by: Elliott Sales de Andrade <quantum.analyst@gmail.com>

Author: 3 people

doc/api/next_api_changes/deprecations/23824-OG.rst

@@ -0,0 +1,16 @@
+``draw_gouraud_triangle``
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+... is deprecated as in most backends this is a redundant call. Use
+`~.RendererBase.draw_gouraud_triangles` instead. A ``draw_gouraud_triangle``
+call in a custom `~matplotlib.artist.Artist` can readily be replaced as::
+
+    self.draw_gouraud_triangles(gc, points.reshape((1, 3, 2)),
+                                colors.reshape((1, 3, 4)), trans)
+
+A `~.RendererBase.draw_gouraud_triangles` method can be implemented from an
+existing ``draw_gouraud_triangle`` method as::
+
+    transform = transform.frozen()
+    for tri, col in zip(triangles_array, colors_array):
+        self.draw_gouraud_triangle(gc, tri, col, transform)

lib/matplotlib/backend_bases.py

@@ -158,7 +158,7 @@ class RendererBase:
 
     * `draw_path`
     * `draw_image`
-    * `draw_gouraud_triangle`
+    * `draw_gouraud_triangles`
 
     The following methods *should* be implemented in the backend for
     optimization reasons:
@@ -286,6 +286,7 @@ def draw_quad_mesh(self, gc, master_transform, meshWidth, meshHeight,
             gc, master_transform, paths, [], offsets, offsetTrans, facecolors,
             edgecolors, linewidths, [], [antialiased], [None], 'screen')
 
+    @_api.deprecated("3.7", alternative="draw_gouraud_triangles")
     def draw_gouraud_triangle(self, gc, points, colors, transform):
         """
         Draw a Gouraud-shaded triangle.
@@ -317,9 +318,7 @@ def draw_gouraud_triangles(self, gc, triangles_array, colors_array,
         transform : `matplotlib.transforms.Transform`
             An affine transform to apply to the points.
         """
-        transform = transform.frozen()
-        for tri, col in zip(triangles_array, colors_array):
-            self.draw_gouraud_triangle(gc, tri, col, transform)
+        raise NotImplementedError
 
     def _iter_collection_raw_paths(self, master_transform, paths,
                                    all_transforms):

lib/matplotlib/backends/backend_svg.py

@@ -801,7 +801,9 @@ def draw_path_collection(self, gc, master_transform, paths, all_transforms,
 
     def draw_gouraud_triangle(self, gc, points, colors, trans):
         # docstring inherited
+        self._draw_gouraud_triangle(gc, points, colors, trans)
 
+    def _draw_gouraud_triangle(self, gc, points, colors, trans):
         # This uses a method described here:
         #
         #   http://www.svgopen.org/2005/papers/Converting3DFaceToSVG/index.html
@@ -936,7 +938,7 @@ def draw_gouraud_triangles(self, gc, triangles_array, colors_array,
         self.writer.start('g', **self._get_clip_attrs(gc))
         transform = transform.frozen()
         for tri, col in zip(triangles_array, colors_array):
-            self.draw_gouraud_triangle(gc, tri, col, transform)
+            self._draw_gouraud_triangle(gc, tri, col, transform)
         self.writer.end('g')
 
     def option_scale_image(self):

lib/matplotlib/collections.py

@@ -2097,7 +2097,7 @@ def _convert_mesh_to_triangles(self, coordinates):
         """
         Convert a given mesh into a sequence of triangles, each point
         with its own color.  The result can be used to construct a call to
-        `~.RendererBase.draw_gouraud_triangle`.
+        `~.RendererBase.draw_gouraud_triangles`.
         """
         if isinstance(coordinates, np.ma.MaskedArray):
             p = coordinates.data