DOC: Add summary lines to plot types.

timhoffm · timhoffm · commit a8d8915de24a · 2024-03-15T21:51:59.000+01:00
IMHO it's meaningful to give a one-sentence summary on the individual pages, e.g. at https://matplotlib.org/stable/plot_types/basic/plot.html#sphx-glr-plot-types-basic-plot-py > Plot y versus x as lines and/or markers. > > See `plot`. is more helpful than just > See `plot`. Users can already decide if that's the correct function for them and whether it's worth following the link. Also, the first sentence is used in the tooltip on the index page, where the current "See ..." is not helpful. I believe it's ok to just copy the text. Automatic insertion or check for consistency are not worth the added effort. First, these summary lines change rarely. Second, even if we improve the method summary and forget to udpate here, nothing really bad happens; we've maybe a slightly less optimal description here, but that's still way better than no description at all. Semi-OT: I changed the barbs summary from > Plot a 2D field of barbs. to > Plot a 2D field of wind barbs. because, AFAIK these are only used for wind, and that makes the context more clear. People outside of metrology may not know what barbs are so giving that extra context is reasonable.
diff --git a/galleries/plot_types/arrays/barbs.py b/galleries/plot_types/arrays/barbs.py
@@ -2,6 +2,7 @@
 =================
 barbs(X, Y, U, V)
 =================
+Plot a 2D field of wind barbs.
 
 See `~matplotlib.axes.Axes.barbs`.
 """
diff --git a/galleries/plot_types/arrays/contour.py b/galleries/plot_types/arrays/contour.py
@@ -2,6 +2,7 @@
 ================
 contour(X, Y, Z)
 ================
+Plot contour lines.
 
 See `~matplotlib.axes.Axes.contour`.
 """
diff --git a/galleries/plot_types/arrays/contourf.py b/galleries/plot_types/arrays/contourf.py
@@ -2,6 +2,7 @@
 =================
 contourf(X, Y, Z)
 =================
+Plot filled contours.
 
 See `~matplotlib.axes.Axes.contourf`.
 """
diff --git a/galleries/plot_types/arrays/imshow.py b/galleries/plot_types/arrays/imshow.py
@@ -2,6 +2,7 @@
 =========
 imshow(Z)
 =========
+Display data as an image, i.e., on a 2D regular raster.
 
 See `~matplotlib.axes.Axes.imshow`.
 """
diff --git a/galleries/plot_types/arrays/pcolormesh.py b/galleries/plot_types/arrays/pcolormesh.py
@@ -2,6 +2,7 @@
 ===================
 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
 the x and y vectors need not be equally spaced (indeed they can be skewed).
diff --git a/galleries/plot_types/arrays/quiver.py b/galleries/plot_types/arrays/quiver.py
@@ -2,6 +2,7 @@
 ==================
 quiver(X, Y, U, V)
 ==================
+Plot a 2D field of arrows.
 
 See `~matplotlib.axes.Axes.quiver`.
 """
diff --git a/galleries/plot_types/arrays/streamplot.py b/galleries/plot_types/arrays/streamplot.py
@@ -2,6 +2,7 @@
 ======================
 streamplot(X, Y, U, V)
 ======================
+Draw streamlines of a vector flow.
 
 See `~matplotlib.axes.Axes.streamplot`.
 """
diff --git a/galleries/plot_types/basic/fill_between.py b/galleries/plot_types/basic/fill_between.py
@@ -2,6 +2,7 @@
 =======================
 fill_between(x, y1, y2)
 =======================
+Fill the area between two horizontal curves.
 
 See `~matplotlib.axes.Axes.fill_between`.
 """
diff --git a/galleries/plot_types/basic/plot.py b/galleries/plot_types/basic/plot.py
@@ -2,6 +2,7 @@
 ==========
 plot(x, y)
 ==========
+Plot y versus x as lines and/or markers.
 
 See `~matplotlib.axes.Axes.plot`.
 """
diff --git a/galleries/plot_types/basic/scatter_plot.py b/galleries/plot_types/basic/scatter_plot.py
@@ -2,6 +2,7 @@
 =============
 scatter(x, y)
 =============
+A scatter plot of y vs. x with varying marker size and/or color.
 
 See `~matplotlib.axes.Axes.scatter`.
 """
diff --git a/galleries/plot_types/basic/stackplot.py b/galleries/plot_types/basic/stackplot.py
@@ -2,6 +2,8 @@
 ===============
 stackplot(x, y)
 ===============
+Draw a stacked area plot or a streamgraph.
+
 See `~matplotlib.axes.Axes.stackplot`
 """
 import matplotlib.pyplot as plt
diff --git a/galleries/plot_types/basic/stairs.py b/galleries/plot_types/basic/stairs.py
@@ -2,6 +2,7 @@
 ==============
 stairs(values)
 ==============
+A stepwise constant function as a line with bounding edges or a filled plot.
 
 See `~matplotlib.axes.Axes.stairs` when plotting :math:`y` between
 :math:`(x_i, x_{i+1})`. For plotting :math:`y` at :math:`x`, see
diff --git a/galleries/plot_types/basic/stem.py b/galleries/plot_types/basic/stem.py
@@ -2,6 +2,7 @@
 ==========
 stem(x, y)
 ==========
+Create a stem plot.
 
 See `~matplotlib.axes.Axes.stem`.
 """
diff --git a/galleries/plot_types/stats/boxplot_plot.py b/galleries/plot_types/stats/boxplot_plot.py
@@ -2,6 +2,7 @@
 ==========
 boxplot(X)
 ==========
+Draw a box and whisker plot.
 
 See `~matplotlib.axes.Axes.boxplot`.
 """
diff --git a/galleries/plot_types/stats/ecdf.py b/galleries/plot_types/stats/ecdf.py
@@ -2,6 +2,7 @@
 =======
 ecdf(x)
 =======
+Compute and plot the empirical cumulative distribution function of x.
 
 See `~matplotlib.axes.Axes.ecdf`.
 """
diff --git a/galleries/plot_types/stats/errorbar_plot.py b/galleries/plot_types/stats/errorbar_plot.py
@@ -2,6 +2,7 @@
 ==========================
 errorbar(x, y, yerr, xerr)
 ==========================
+Plot y versus x as lines and/or markers with attached errorbars.
 
 See `~matplotlib.axes.Axes.errorbar`.
 """
diff --git a/galleries/plot_types/stats/eventplot.py b/galleries/plot_types/stats/eventplot.py
@@ -2,6 +2,7 @@
 ============
 eventplot(D)
 ============
+Plot identical parallel lines at the given positions.
 
 See `~matplotlib.axes.Axes.eventplot`.
 """
diff --git a/galleries/plot_types/stats/hexbin.py b/galleries/plot_types/stats/hexbin.py
@@ -2,6 +2,7 @@
 ===============
 hexbin(x, y, C)
 ===============
+Make a 2D hexagonal binning plot of points x, y.
 
 See `~matplotlib.axes.Axes.hexbin`.
 """
diff --git a/galleries/plot_types/stats/hist2d.py b/galleries/plot_types/stats/hist2d.py
@@ -2,6 +2,7 @@
 ============
 hist2d(x, y)
 ============
+Make a 2D histogram plot.
 
 See `~matplotlib.axes.Axes.hist2d`.
 """
diff --git a/galleries/plot_types/stats/hist_plot.py b/galleries/plot_types/stats/hist_plot.py
@@ -2,6 +2,7 @@
 =======
 hist(x)
 =======
+Compute and plot a histogram.
 
 See `~matplotlib.axes.Axes.hist`.
 """
diff --git a/galleries/plot_types/stats/pie.py b/galleries/plot_types/stats/pie.py
@@ -2,6 +2,7 @@
 ======
 pie(x)
 ======
+Plot a pie chart.
 
 See `~matplotlib.axes.Axes.pie`.
 """
diff --git a/galleries/plot_types/stats/violin.py b/galleries/plot_types/stats/violin.py
@@ -2,6 +2,7 @@
 =============
 violinplot(D)
 =============
+Make a violin plot.
 
 See `~matplotlib.axes.Axes.violinplot`.
 """
diff --git a/galleries/plot_types/unstructured/tricontour.py b/galleries/plot_types/unstructured/tricontour.py
@@ -2,6 +2,7 @@
 ===================
 tricontour(x, y, z)
 ===================
+Draw contour lines on an unstructured triangular grid.
 
 See `~matplotlib.axes.Axes.tricontour`.
 """
diff --git a/galleries/plot_types/unstructured/tricontourf.py b/galleries/plot_types/unstructured/tricontourf.py
@@ -2,6 +2,7 @@
 ====================
 tricontourf(x, y, z)
 ====================
+Draw contour regions on an unstructured triangular grid.
 
 See `~matplotlib.axes.Axes.tricontourf`.
 """
diff --git a/galleries/plot_types/unstructured/tripcolor.py b/galleries/plot_types/unstructured/tripcolor.py
@@ -2,6 +2,7 @@
 ==================
 tripcolor(x, y, z)
 ==================
+Create a pseudocolor plot of an unstructured triangular grid.
 
 See `~matplotlib.axes.Axes.tripcolor`.
 """
diff --git a/galleries/plot_types/unstructured/triplot.py b/galleries/plot_types/unstructured/triplot.py
@@ -2,6 +2,7 @@
 =============
 triplot(x, y)
 =============
+Draw an unstructured triangular grid as lines and/or markers.
 
 See `~matplotlib.axes.Axes.triplot`.
 """
diff --git a/lib/matplotlib/quiver.py b/lib/matplotlib/quiver.py
@@ -727,7 +727,7 @@ def _h_arrows(self, length):
 
 
 _barbs_doc = r"""
-Plot a 2D field of barbs.
+Plot a 2D field of wind barbs.
 
 Call signature::
 
diff --git a/lib/matplotlib/stackplot.py b/lib/matplotlib/stackplot.py
@@ -19,7 +19,7 @@ def stackplot(axes, x, *args,
               labels=(), colors=None, hatch=None, baseline='zero',
               **kwargs):
     """
-    Draw a stacked area plot.
+    Draw a stacked area plot or a streamgraph.
 
     Parameters
     ----------
