From a702f66f5e4aea46cdefa2b238cffbcdf046cd54 Mon Sep 17 00:00:00 2001
From: Jon Seddon <jon.seddon@metoffice.gov.uk>
Date: Sat, 16 May 2020 18:31:44 +0100
Subject: [PATCH 01/17] Add plot and gallery example

---
 .../example_code/Meteorology/wind_barbs.py    | 61 +++++++++++++++++++
 lib/iris/plot.py                              | 48 +++++++++++++++
 2 files changed, 109 insertions(+)
 create mode 100644 docs/iris/example_code/Meteorology/wind_barbs.py

diff --git a/docs/iris/example_code/Meteorology/wind_barbs.py b/docs/iris/example_code/Meteorology/wind_barbs.py
new file mode 100644
index 0000000000..33334a3199
--- /dev/null
+++ b/docs/iris/example_code/Meteorology/wind_barbs.py
@@ -0,0 +1,61 @@
+"""
+Plotting wind direction using barbs
+===========================================================
+
+This example demonstrates using barbs to plot wind speed contours and wind
+direction barbs from wind vector component input data. The vector components
+are co-located in space in this case.
+
+The magnitude of the wind in the original data is low and so doesn't illustrate
+the full range of barbs. The wind is scaled to simulate a storm that better
+illustrates the range of barbs that are available.
+"""
+
+import matplotlib.pyplot as plt
+
+import iris
+import iris.plot as iplt
+import iris.quickplot as qplt
+
+
+def main():
+    # Load the u and v components of wind from a pp file
+    infile = iris.sample_data_path("wind_speed_lake_victoria.pp")
+
+    uwind = iris.load_cube(infile, "x_wind")
+    vwind = iris.load_cube(infile, "y_wind")
+
+    uwind.convert_units('knot')
+    vwind.convert_units('knot')
+
+    # To illustrate the full range of barbs scale the wind speed up to pretend
+    # that a storm is passing over
+    magnitude = (uwind ** 2 + vwind ** 2) ** 0.5
+    magnitude.convert_units('knot')
+    max_speed = magnitude.collapsed(('latitude', 'longitude'),
+                                    iris.analysis.MAX).data
+    max_desired = 65
+
+    uwind = uwind / max_speed * max_desired
+    vwind = vwind / max_speed * max_desired
+
+    # Create a cube containing the wind speed
+    windspeed = (uwind ** 2 + vwind ** 2) ** 0.5
+    windspeed.rename('windspeed')
+    windspeed.convert_units('knot')
+
+    plt.figure()
+
+    # Plot the wind speed as a contour plot
+    qplt.contourf(windspeed)
+
+    # Add wind barbs except for the outermost values which overhang the edge
+    # of the plot if left
+    iplt.barbs(uwind[1:-1, 1:-1], vwind[1:-1, 1:-1], pivot='middle')
+
+    plt.title("Wind speed over Lake Victoria\nduring a simulated storm")
+    qplt.show()
+
+
+if __name__ == "__main__":
+    main()
diff --git a/lib/iris/plot.py b/lib/iris/plot.py
index a49957accf..c51d88b4e8 100644
--- a/lib/iris/plot.py
+++ b/lib/iris/plot.py
@@ -1418,6 +1418,54 @@ def _vector_component_args(x_points, y_points, u_data, *args, **kwargs):
     return ((x_points, y_points, u_data, v_data), kwargs)
 
 
+def barbs(u_cube, v_cube, *args, **kwargs):
+    """
+    Draws a barb plot from two vector component cubes.
+
+    Args:
+
+    * u_cube, v_cube : (:class:`~iris.cube.Cube`)
+        u and v vector components.  Must have same shape and units of knot.
+        If the cubes have geographic coordinates, the values are treated as
+        true distance differentials, e.g. windspeeds, and *not* map coordinate
+        vectors.  The components are aligned with the North and East of the
+        cube coordinate system.
+
+    .. Note:
+
+        At present, if u_cube and v_cube have geographic coordinates, then they
+        must be in a lat-lon coordinate system, though it may be a rotated one.
+        To transform wind values between coordinate systems, use
+        :func:`iris.analysis.cartography.rotate_vectors`.
+        To transform coordinate grid points, you will need to create
+        2-dimensional arrays of x and y values.  These can be transformed with
+        :meth:`cartopy.crs.CRS.transform_points`.
+
+    Kwargs:
+
+    * coords: (list of :class:`~iris.coords.Coord` or string)
+        Coordinates or coordinate names. Use the given coordinates as the axes
+        for the plot. The order of the given coordinates indicates which axis
+        to use for each, where the first element is the horizontal
+        axis of the plot and the second element is the vertical axis
+        of the plot.
+
+    * axes: the :class:`matplotlib.axes.Axes` to use for drawing.
+        Defaults to the current axes if none provided.
+
+    See :func:`matplotlib.pyplot.barbs` for details of other valid
+    keyword arguments.
+
+    """
+    #
+    # TODO: check u + v cubes for compatibility.
+    #
+    kwargs["_v_data"] = v_cube.data
+    return _draw_2d_from_points(
+        "barbs", _vector_component_args, u_cube, *args, **kwargs
+    )
+
+
 def quiver(u_cube, v_cube, *args, **kwargs):
     """
     Draws an arrow plot from two vector component cubes.

From 627ab4c74773282707746af792a20e3df85aa3c0 Mon Sep 17 00:00:00 2001
From: Jon Seddon <jon.seddon@metoffice.gov.uk>
Date: Sat, 16 May 2020 18:37:04 +0100
Subject: [PATCH 02/17] Add a what's new

---
 .../contributions_3.0.0/newfeature_2020-May-16_barbs.txt_        | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2020-May-16_barbs.txt_

diff --git a/docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2020-May-16_barbs.txt_ b/docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2020-May-16_barbs.txt_
new file mode 100644
index 0000000000..becea19d2c
--- /dev/null
+++ b/docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2020-May-16_barbs.txt_
@@ -0,0 +1 @@
+Add an Iris plot for matplotlib.pyplot.barbs along with a gallery example.
\ No newline at end of file

From b8a3603a65f224d1db1c5885138d53b343c07b4f Mon Sep 17 00:00:00 2001
From: Jon Seddon <jon.seddon@metoffice.gov.uk>
Date: Sun, 17 May 2020 19:11:14 +0100
Subject: [PATCH 03/17] Added test and reduced size of gallery example

---
 .../example_code/Meteorology/wind_barbs.py    |  2 +-
 docs/iris/example_tests/test_wind_barbs.py    | 30 +++++++++++++++++++
 ....txt_ => newfeature_2020-May-16_barbs.txt} |  0
 3 files changed, 31 insertions(+), 1 deletion(-)
 create mode 100644 docs/iris/example_tests/test_wind_barbs.py
 rename docs/iris/src/whatsnew/contributions_3.0.0/{newfeature_2020-May-16_barbs.txt_ => newfeature_2020-May-16_barbs.txt} (100%)

diff --git a/docs/iris/example_code/Meteorology/wind_barbs.py b/docs/iris/example_code/Meteorology/wind_barbs.py
index 33334a3199..40f812a919 100644
--- a/docs/iris/example_code/Meteorology/wind_barbs.py
+++ b/docs/iris/example_code/Meteorology/wind_barbs.py
@@ -51,7 +51,7 @@ def main():
 
     # Add wind barbs except for the outermost values which overhang the edge
     # of the plot if left
-    iplt.barbs(uwind[1:-1, 1:-1], vwind[1:-1, 1:-1], pivot='middle')
+    iplt.barbs(uwind[1:-1, 1:-1], vwind[1:-1, 1:-1], pivot='middle', length=6)
 
     plt.title("Wind speed over Lake Victoria\nduring a simulated storm")
     qplt.show()
diff --git a/docs/iris/example_tests/test_wind_barbs.py b/docs/iris/example_tests/test_wind_barbs.py
new file mode 100644
index 0000000000..c56ce8ef53
--- /dev/null
+++ b/docs/iris/example_tests/test_wind_barbs.py
@@ -0,0 +1,30 @@
+# Copyright Iris contributors
+#
+# This file is part of Iris and is released under the LGPL license.
+# See COPYING and COPYING.LESSER in the root of the repository for full
+# licensing details.
+
+# Import Iris tests first so that some things can be initialised before
+# importing anything else.
+import iris.tests as tests
+
+from .extest_util import (
+    add_examples_to_path,
+    show_replaced_by_check_graphic,
+    fail_any_deprecation_warnings,
+)
+
+
+class TestWindBarbs(tests.GraphicsTest):
+    """Test the wind_barbs example code."""
+
+    def test_wind_speed(self):
+        with fail_any_deprecation_warnings():
+            with add_examples_to_path():
+                import wind_barbs
+            with show_replaced_by_check_graphic(self):
+                wind_barbs.main()
+
+
+if __name__ == "__main__":
+    tests.main()
diff --git a/docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2020-May-16_barbs.txt_ b/docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2020-May-16_barbs.txt
similarity index 100%
rename from docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2020-May-16_barbs.txt_
rename to docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2020-May-16_barbs.txt

From 1b605596e79351f82f658f5184295c22c6082c7b Mon Sep 17 00:00:00 2001
From: Jon Seddon <jon.seddon@metoffice.gov.uk>
Date: Sun, 17 May 2020 19:15:18 +0100
Subject: [PATCH 04/17] Painted it black

---
 .../iris/example_code/Meteorology/wind_barbs.py | 17 +++++++++--------
 1 file changed, 9 insertions(+), 8 deletions(-)

diff --git a/docs/iris/example_code/Meteorology/wind_barbs.py b/docs/iris/example_code/Meteorology/wind_barbs.py
index 40f812a919..c1dc83f681 100644
--- a/docs/iris/example_code/Meteorology/wind_barbs.py
+++ b/docs/iris/example_code/Meteorology/wind_barbs.py
@@ -25,15 +25,16 @@ def main():
     uwind = iris.load_cube(infile, "x_wind")
     vwind = iris.load_cube(infile, "y_wind")
 
-    uwind.convert_units('knot')
-    vwind.convert_units('knot')
+    uwind.convert_units("knot")
+    vwind.convert_units("knot")
 
     # To illustrate the full range of barbs scale the wind speed up to pretend
     # that a storm is passing over
     magnitude = (uwind ** 2 + vwind ** 2) ** 0.5
-    magnitude.convert_units('knot')
-    max_speed = magnitude.collapsed(('latitude', 'longitude'),
-                                    iris.analysis.MAX).data
+    magnitude.convert_units("knot")
+    max_speed = magnitude.collapsed(
+        ("latitude", "longitude"), iris.analysis.MAX
+    ).data
     max_desired = 65
 
     uwind = uwind / max_speed * max_desired
@@ -41,8 +42,8 @@ def main():
 
     # Create a cube containing the wind speed
     windspeed = (uwind ** 2 + vwind ** 2) ** 0.5
-    windspeed.rename('windspeed')
-    windspeed.convert_units('knot')
+    windspeed.rename("windspeed")
+    windspeed.convert_units("knot")
 
     plt.figure()
 
@@ -51,7 +52,7 @@ def main():
 
     # Add wind barbs except for the outermost values which overhang the edge
     # of the plot if left
-    iplt.barbs(uwind[1:-1, 1:-1], vwind[1:-1, 1:-1], pivot='middle', length=6)
+    iplt.barbs(uwind[1:-1, 1:-1], vwind[1:-1, 1:-1], pivot="middle", length=6)
 
     plt.title("Wind speed over Lake Victoria\nduring a simulated storm")
     qplt.show()

From a8eab8ff79a1ffbcc62f9e89e0dcc0c9499618fe Mon Sep 17 00:00:00 2001
From: Jon Seddon <jon.seddon@metoffice.gov.uk>
Date: Sun, 17 May 2020 20:31:32 +0100
Subject: [PATCH 05/17] Added test to imagerepo.json but name of file in repo
 will be wrong

---
 docs/iris/example_tests/test_wind_barbs.py | 2 +-
 lib/iris/tests/results/imagerepo.json      | 3 +++
 2 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/docs/iris/example_tests/test_wind_barbs.py b/docs/iris/example_tests/test_wind_barbs.py
index c56ce8ef53..4e2ce9dfed 100644
--- a/docs/iris/example_tests/test_wind_barbs.py
+++ b/docs/iris/example_tests/test_wind_barbs.py
@@ -18,7 +18,7 @@
 class TestWindBarbs(tests.GraphicsTest):
     """Test the wind_barbs example code."""
 
-    def test_wind_speed(self):
+    def test_wind_barbs(self):
         with fail_any_deprecation_warnings():
             with add_examples_to_path():
                 import wind_barbs
diff --git a/lib/iris/tests/results/imagerepo.json b/lib/iris/tests/results/imagerepo.json
index 8c6f622991..2d17605b37 100644
--- a/lib/iris/tests/results/imagerepo.json
+++ b/lib/iris/tests/results/imagerepo.json
@@ -143,6 +143,9 @@
         "https://scitools.github.io/test-iris-imagehash/images/v4/fa8172d0847ecd2bc913939c36846c714933799cc3cc8727e67639f939996a58.png",
         "https://scitools.github.io/test-iris-imagehash/images/v4/fa8172c6857ecd38cb3392ce36c564311931d85ec64e9787719a39993c316e66.png"
     ],
+    "example_tests.test_wind_barbs.TestWindBarbs.test_wind_barbs.0": [
+        "https://scitools.github.io/test-iris-imagehash/images/v4/a3ff34e87f0049496d17c4d9c04fc225d256971392d39f1696df0f16cec00f36.png"
+    ],
     "gallery_tests.test_plot_wind_speed.TestWindSpeed.test_plot_wind_speed.0": [
         "https://scitools.github.io/test-iris-imagehash/images/v4/bcf924fb9306930ce12ccf97c73236b28ecec4cd3e29847b18e639e6c14f1a09.png",
         "https://scitools.github.io/test-iris-imagehash/images/v4/e9e960e996169306c1fe9e96c29e36739e13c06c3d61c07f39a139e1c07f3f01.png"

From 05d43cab9517e12fa2934b0c1c3d4cfe72e25905 Mon Sep 17 00:00:00 2001
From: Jon Seddon <jon.seddon@metoffice.gov.uk>
Date: Sun, 24 May 2020 09:28:03 +0100
Subject: [PATCH 06/17] Correct hash inserted

---
 lib/iris/tests/results/imagerepo.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/iris/tests/results/imagerepo.json b/lib/iris/tests/results/imagerepo.json
index 2d17605b37..cbafaca4ec 100644
--- a/lib/iris/tests/results/imagerepo.json
+++ b/lib/iris/tests/results/imagerepo.json
@@ -144,7 +144,7 @@
         "https://scitools.github.io/test-iris-imagehash/images/v4/fa8172c6857ecd38cb3392ce36c564311931d85ec64e9787719a39993c316e66.png"
     ],
     "example_tests.test_wind_barbs.TestWindBarbs.test_wind_barbs.0": [
-        "https://scitools.github.io/test-iris-imagehash/images/v4/a3ff34e87f0049496d17c4d9c04fc225d256971392d39f1696df0f16cec00f36.png"
+        "https://scitools.github.io/test-iris-imagehash/images/v4/e9e960e996169316c1fe9e96c29e36739e13c07c3d61c07f39a13921c07f3e21.png"
     ],
     "gallery_tests.test_plot_wind_speed.TestWindSpeed.test_plot_wind_speed.0": [
         "https://scitools.github.io/test-iris-imagehash/images/v4/bcf924fb9306930ce12ccf97c73236b28ecec4cd3e29847b18e639e6c14f1a09.png",

From 0b2d3fe92db25831ceb2dba19e32d815116514e4 Mon Sep 17 00:00:00 2001
From: Jon Seddon <jon.seddon@metoffice.gov.uk>
Date: Wed, 30 Dec 2020 13:02:51 +0000
Subject: [PATCH 07/17] Correctly resolved merge conflict

---
 .../meteorology/plot_wind_barbs.py}                    |  4 ----
 .../test_plot_wind_barbs.py}                           | 10 +++++-----
 lib/iris/tests/results/imagerepo.json                  |  2 +-
 3 files changed, 6 insertions(+), 10 deletions(-)
 rename docs/{iris/example_code/Meteorology/wind_barbs.py => gallery_code/meteorology/plot_wind_barbs.py} (97%)
 rename docs/{iris/example_tests/test_wind_barbs.py => gallery_tests/test_plot_wind_barbs.py} (79%)

diff --git a/docs/iris/example_code/Meteorology/wind_barbs.py b/docs/gallery_code/meteorology/plot_wind_barbs.py
similarity index 97%
rename from docs/iris/example_code/Meteorology/wind_barbs.py
rename to docs/gallery_code/meteorology/plot_wind_barbs.py
index c1dc83f681..2b65fceae9 100644
--- a/docs/iris/example_code/Meteorology/wind_barbs.py
+++ b/docs/gallery_code/meteorology/plot_wind_barbs.py
@@ -56,7 +56,3 @@ def main():
 
     plt.title("Wind speed over Lake Victoria\nduring a simulated storm")
     qplt.show()
-
-
-if __name__ == "__main__":
-    main()
diff --git a/docs/iris/example_tests/test_wind_barbs.py b/docs/gallery_tests/test_plot_wind_barbs.py
similarity index 79%
rename from docs/iris/example_tests/test_wind_barbs.py
rename to docs/gallery_tests/test_plot_wind_barbs.py
index 4e2ce9dfed..1c47bbb588 100644
--- a/docs/iris/example_tests/test_wind_barbs.py
+++ b/docs/gallery_tests/test_plot_wind_barbs.py
@@ -8,8 +8,8 @@
 # importing anything else.
 import iris.tests as tests
 
-from .extest_util import (
-    add_examples_to_path,
+from .gallerytest_util import (
+    add_gallery_to_path,
     show_replaced_by_check_graphic,
     fail_any_deprecation_warnings,
 )
@@ -20,10 +20,10 @@ class TestWindBarbs(tests.GraphicsTest):
 
     def test_wind_barbs(self):
         with fail_any_deprecation_warnings():
-            with add_examples_to_path():
-                import wind_barbs
+            with add_gallery_to_path():
+                import plot_wind_barbs
             with show_replaced_by_check_graphic(self):
-                wind_barbs.main()
+                plot_wind_barbs.main()
 
 
 if __name__ == "__main__":
diff --git a/lib/iris/tests/results/imagerepo.json b/lib/iris/tests/results/imagerepo.json
index cbafaca4ec..7d3d4db3f8 100644
--- a/lib/iris/tests/results/imagerepo.json
+++ b/lib/iris/tests/results/imagerepo.json
@@ -143,7 +143,7 @@
         "https://scitools.github.io/test-iris-imagehash/images/v4/fa8172d0847ecd2bc913939c36846c714933799cc3cc8727e67639f939996a58.png",
         "https://scitools.github.io/test-iris-imagehash/images/v4/fa8172c6857ecd38cb3392ce36c564311931d85ec64e9787719a39993c316e66.png"
     ],
-    "example_tests.test_wind_barbs.TestWindBarbs.test_wind_barbs.0": [
+    "gallery_tests.test_plot_wind_barbs.TestWindBarbs.test_wind_barbs.0": [
         "https://scitools.github.io/test-iris-imagehash/images/v4/e9e960e996169316c1fe9e96c29e36739e13c07c3d61c07f39a13921c07f3e21.png"
     ],
     "gallery_tests.test_plot_wind_speed.TestWindSpeed.test_plot_wind_speed.0": [

From d72fcea67d106b6337c24a4b5eeab0199e701911 Mon Sep 17 00:00:00 2001
From: Jon Seddon <jon.seddon@metoffice.gov.uk>
Date: Wed, 30 Dec 2020 17:15:33 +0000
Subject: [PATCH 08/17] Hopefully fully compliant with new style gallery now

---
 docs/gallery_code/meteorology/plot_wind_barbs.py              | 4 ++++
 .../contributions_3.0.0/newfeature_2020-May-16_barbs.txt      | 1 -
 docs/src/whatsnew/latest.rst                                  | 3 +++
 3 files changed, 7 insertions(+), 1 deletion(-)
 delete mode 100644 docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2020-May-16_barbs.txt

diff --git a/docs/gallery_code/meteorology/plot_wind_barbs.py b/docs/gallery_code/meteorology/plot_wind_barbs.py
index 2b65fceae9..3e4df69ad2 100644
--- a/docs/gallery_code/meteorology/plot_wind_barbs.py
+++ b/docs/gallery_code/meteorology/plot_wind_barbs.py
@@ -56,3 +56,7 @@ def main():
 
     plt.title("Wind speed over Lake Victoria\nduring a simulated storm")
     qplt.show()
+
+
+if __name__ == "__main__":
+    main()
\ No newline at end of file
diff --git a/docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2020-May-16_barbs.txt b/docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2020-May-16_barbs.txt
deleted file mode 100644
index becea19d2c..0000000000
--- a/docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2020-May-16_barbs.txt
+++ /dev/null
@@ -1 +0,0 @@
-Add an Iris plot for matplotlib.pyplot.barbs along with a gallery example.
\ No newline at end of file
diff --git a/docs/src/whatsnew/latest.rst b/docs/src/whatsnew/latest.rst
index 6e50aaa487..065c3d56f3 100644
--- a/docs/src/whatsnew/latest.rst
+++ b/docs/src/whatsnew/latest.rst
@@ -42,6 +42,9 @@ This document explains the changes made to Iris for this release
    the primary coordinate being plotted against is a vertical coordinate. E.g.
    ``iris.plot.plot(z_cube)`` will produce a z-vs-phenomenon plot, where before
    it would have produced a phenomenon-vs-z plot. (:pull:`3906`)
+#. `@jonseddon`_ added :meth:`iris.plot.barbs` to provide a convenient way to
+   use :func:`matplotlib.pyplot.barbs` with Iris cubes. A gallery example was
+   included to illustrate the new method's use. (:pull:`3710`)
 
 #. `@bjlittle`_ introduced :func:`iris.common.metadata.hexdigest` to the
    public API. Previously it was a private function introduced in ``v3.0.0``.

From fba7ab806efa9198bb7baf7e2074d8d4f6a5cd99 Mon Sep 17 00:00:00 2001
From: Jon Seddon <jon.seddon@metoffice.gov.uk>
Date: Wed, 10 Feb 2021 18:09:48 +0000
Subject: [PATCH 09/17] Consistency with new style documentation

---
 docs/gallery_code/meteorology/plot_wind_barbs.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/gallery_code/meteorology/plot_wind_barbs.py b/docs/gallery_code/meteorology/plot_wind_barbs.py
index 3e4df69ad2..773b12a1fd 100644
--- a/docs/gallery_code/meteorology/plot_wind_barbs.py
+++ b/docs/gallery_code/meteorology/plot_wind_barbs.py
@@ -1,6 +1,6 @@
 """
-Plotting wind direction using barbs
-===========================================================
+Plotting Wind Direction Using Barbs
+===================================
 
 This example demonstrates using barbs to plot wind speed contours and wind
 direction barbs from wind vector component input data. The vector components
@@ -59,4 +59,4 @@ def main():
 
 
 if __name__ == "__main__":
-    main()
\ No newline at end of file
+    main()

From 564312b56a7f689c10826accae30a06aee31609b Mon Sep 17 00:00:00 2001
From: Jon Seddon <jon.seddon@metoffice.gov.uk>
Date: Wed, 4 Aug 2021 13:46:56 +0100
Subject: [PATCH 10/17] Improved language as Lake Victoria is not relevant and
 shorelines are not included in this simulated data.

---
 docs/gallery_code/meteorology/plot_wind_barbs.py | 4 ++--
 lib/iris/tests/results/imagerepo.json            | 3 ++-
 2 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/docs/gallery_code/meteorology/plot_wind_barbs.py b/docs/gallery_code/meteorology/plot_wind_barbs.py
index 773b12a1fd..c3c056eb4a 100644
--- a/docs/gallery_code/meteorology/plot_wind_barbs.py
+++ b/docs/gallery_code/meteorology/plot_wind_barbs.py
@@ -28,7 +28,7 @@ def main():
     uwind.convert_units("knot")
     vwind.convert_units("knot")
 
-    # To illustrate the full range of barbs scale the wind speed up to pretend
+    # To illustrate the full range of barbs, scale the wind speed up to pretend
     # that a storm is passing over
     magnitude = (uwind ** 2 + vwind ** 2) ** 0.5
     magnitude.convert_units("knot")
@@ -54,7 +54,7 @@ def main():
     # of the plot if left
     iplt.barbs(uwind[1:-1, 1:-1], vwind[1:-1, 1:-1], pivot="middle", length=6)
 
-    plt.title("Wind speed over Lake Victoria\nduring a simulated storm")
+    plt.title("Wind speed during a simulated storm")
     qplt.show()
 
 
diff --git a/lib/iris/tests/results/imagerepo.json b/lib/iris/tests/results/imagerepo.json
index 7d3d4db3f8..13abe35f08 100644
--- a/lib/iris/tests/results/imagerepo.json
+++ b/lib/iris/tests/results/imagerepo.json
@@ -144,7 +144,8 @@
         "https://scitools.github.io/test-iris-imagehash/images/v4/fa8172c6857ecd38cb3392ce36c564311931d85ec64e9787719a39993c316e66.png"
     ],
     "gallery_tests.test_plot_wind_barbs.TestWindBarbs.test_wind_barbs.0": [
-        "https://scitools.github.io/test-iris-imagehash/images/v4/e9e960e996169316c1fe9e96c29e36739e13c07c3d61c07f39a13921c07f3e21.png"
+        "https://scitools.github.io/test-iris-imagehash/images/v4/e9e960e996169316c1fe9e96c29e36739e13c07c3d61c07f39a13921c07f3e21.png",
+        "https://scitools.github.io/test-iris-imagehash/images/v4/e9e161e996169316c1fe9e96c29e36739e13c07c3d61c07f39813929c07f3f01.png"
     ],
     "gallery_tests.test_plot_wind_speed.TestWindSpeed.test_plot_wind_speed.0": [
         "https://scitools.github.io/test-iris-imagehash/images/v4/bcf924fb9306930ce12ccf97c73236b28ecec4cd3e29847b18e639e6c14f1a09.png",

From 4303bde7291027361ff1e242d3f22a22375664c9 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Wed, 4 Aug 2021 12:48:30 +0000
Subject: [PATCH 11/17] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 docs/gallery_tests/test_plot_wind_barbs.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/gallery_tests/test_plot_wind_barbs.py b/docs/gallery_tests/test_plot_wind_barbs.py
index 1c47bbb588..472da0ac53 100644
--- a/docs/gallery_tests/test_plot_wind_barbs.py
+++ b/docs/gallery_tests/test_plot_wind_barbs.py
@@ -10,8 +10,8 @@
 
 from .gallerytest_util import (
     add_gallery_to_path,
-    show_replaced_by_check_graphic,
     fail_any_deprecation_warnings,
+    show_replaced_by_check_graphic,
 )
 
 

From c99fa2a26964833b79b857ef00732dfdbaf0f1a5 Mon Sep 17 00:00:00 2001
From: Jon Seddon <jon.seddon@metoffice.gov.uk>
Date: Thu, 5 Aug 2021 12:56:53 +0100
Subject: [PATCH 12/17] Clarify units

---
 lib/iris/plot.py | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/lib/iris/plot.py b/lib/iris/plot.py
index c51d88b4e8..6291d5efc0 100644
--- a/lib/iris/plot.py
+++ b/lib/iris/plot.py
@@ -1420,12 +1420,13 @@ def _vector_component_args(x_points, y_points, u_data, *args, **kwargs):
 
 def barbs(u_cube, v_cube, *args, **kwargs):
     """
-    Draws a barb plot from two vector component cubes.
+    Draws a barb plot from two vector component cubes. Triangles, full-lines
+    and half-lines represent increments of 50, 10 and 5 respectively.
 
     Args:
 
     * u_cube, v_cube : (:class:`~iris.cube.Cube`)
-        u and v vector components.  Must have same shape and units of knot.
+        u and v vector components.  Must have same shape and units.
         If the cubes have geographic coordinates, the values are treated as
         true distance differentials, e.g. windspeeds, and *not* map coordinate
         vectors.  The components are aligned with the North and East of the

From 69ff70d91d99276110ff29031346650bec903d85 Mon Sep 17 00:00:00 2001
From: Jon Seddon <jon.seddon@metoffice.gov.uk>
Date: Thu, 5 Aug 2021 12:58:36 +0100
Subject: [PATCH 13/17] Correct function name.

---
 lib/iris/plot.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/lib/iris/plot.py b/lib/iris/plot.py
index 6291d5efc0..27aacdf08e 100644
--- a/lib/iris/plot.py
+++ b/lib/iris/plot.py
@@ -1437,7 +1437,7 @@ def barbs(u_cube, v_cube, *args, **kwargs):
         At present, if u_cube and v_cube have geographic coordinates, then they
         must be in a lat-lon coordinate system, though it may be a rotated one.
         To transform wind values between coordinate systems, use
-        :func:`iris.analysis.cartography.rotate_vectors`.
+        :func:`iris.analysis.cartography.rotate_grid_vectors`.
         To transform coordinate grid points, you will need to create
         2-dimensional arrays of x and y values.  These can be transformed with
         :meth:`cartopy.crs.CRS.transform_points`.
@@ -1485,7 +1485,7 @@ def quiver(u_cube, v_cube, *args, **kwargs):
         At present, if u_cube and v_cube have geographic coordinates, then they
         must be in a lat-lon coordinate system, though it may be a rotated one.
         To transform wind values between coordinate systems, use
-        :func:`iris.analysis.cartography.rotate_vectors`.
+        :func:`iris.analysis.cartography.rotate_grid_vectors`.
         To transform coordinate grid points, you will need to create
         2-dimensional arrays of x and y values.  These can be transformed with
         :meth:`cartopy.crs.CRS.transform_points`.

From 5d67a674704244a6d2563f3bc6cb0b24d21f248f Mon Sep 17 00:00:00 2001
From: Jon Seddon <jon.seddon@metoffice.gov.uk>
Date: Thu, 5 Aug 2021 18:03:51 +0100
Subject: [PATCH 14/17] Test vector plots

---
 .../integration/plot/test_vector_plots.py     | 36 ++++++++++++++++---
 lib/iris/tests/results/imagerepo.json         | 15 ++++++++
 2 files changed, 47 insertions(+), 4 deletions(-)

diff --git a/lib/iris/tests/integration/plot/test_vector_plots.py b/lib/iris/tests/integration/plot/test_vector_plots.py
index 7ffbce6eff..03d43c7868 100644
--- a/lib/iris/tests/integration/plot/test_vector_plots.py
+++ b/lib/iris/tests/integration/plot/test_vector_plots.py
@@ -24,16 +24,16 @@
 if tests.MPL_AVAILABLE:
     import matplotlib.pyplot as plt
 
-    from iris.plot import quiver
+    from iris.plot import barbs, quiver
 
 
 @tests.skip_plot
 class MixinVectorPlotCases:
     """
-    Test examples mixin, used by separate quiver + streamplot classes.
+    Test examples mixin, used by separate barb, quiver + streamplot classes.
 
-    NOTE: at present for quiver only, as streamplot does not support arbitrary
-    coordinates.
+    NOTE: at present for barb and quiver only, as streamplot does not support
+    arbitrary coordinates.
 
     """
 
@@ -193,6 +193,34 @@ def test_circular_longitude(self):
         self.plot("circular", u_cube, v_cube, coords=("longitude", "latitude"))
 
 
+class TestBarbs(MixinVectorPlotCases, tests.GraphicsTest):
+    def setUp(self):
+        super().setUp()
+
+    @staticmethod
+    def _nonlatlon_xyuv():
+        # Increase the range of wind speeds used in the barbs test to test more
+        # barbs shapes than just circles
+        x, y, u, v = MixinVectorPlotCases._nonlatlon_xyuv()
+        scale_factor = 50
+        u *= scale_factor
+        v *= scale_factor
+        return x, y, u, v
+
+    @staticmethod
+    def _latlon_uv_cubes(grid_cube):
+        # Increase the range of wind speeds used in the barbs test to test all
+        # barbs shapes
+        u_cube, v_cube = MixinVectorPlotCases._latlon_uv_cubes(grid_cube)
+        scale_factor = 30
+        u_cube.data *= scale_factor
+        v_cube.data *= scale_factor
+        return  u_cube, v_cube
+
+    def plot_function_to_test(self):
+        return barbs
+
+
 class TestQuiver(MixinVectorPlotCases, tests.GraphicsTest):
     def setUp(self):
         super().setUp()
diff --git a/lib/iris/tests/results/imagerepo.json b/lib/iris/tests/results/imagerepo.json
index 13abe35f08..35ef4d00d4 100644
--- a/lib/iris/tests/results/imagerepo.json
+++ b/lib/iris/tests/results/imagerepo.json
@@ -177,6 +177,21 @@
     "iris.tests.integration.plot.test_plot_2d_coords.Test2dContour.test_2d_coords_contour.0": [
         "https://scitools.github.io/test-iris-imagehash/images/v4/b4b2643ecb05cb43b0f23d80c53c4e1d3e5990eb1f81c19f2f983cb1c4ff3e42.png"
     ],
+    "iris.tests.integration.plot.test_vector_plots.TestBarbs.test_2d_plain_latlon.0": [
+        "https://scitools.github.io/test-iris-imagehash/images/v4/eb036726c47c9273918e6e2c6f216336787590eb969a165890ee6c676925b3b3.png"
+    ],
+    "iris.tests.integration.plot.test_vector_plots.TestBarbs.test_2d_plain_latlon_on_polar_map.0": [
+        "https://scitools.github.io/test-iris-imagehash/images/v4/e66d673c999031cd6667663398dc332c676364e798959336636660d933998666.png"
+    ],
+    "iris.tests.integration.plot.test_vector_plots.TestBarbs.test_2d_rotated_latlon.0": [
+        "https://scitools.github.io/test-iris-imagehash/images/v4/eba037a4c479c273b2963f2c6f6126966865d86f969e33c9b1706c26692793b0.png"
+    ],
+    "iris.tests.integration.plot.test_vector_plots.TestBarbs.test_non_latlon_1d_coords.0": [
+        "https://scitools.github.io/test-iris-imagehash/images/v4/a7ac334934d2e65c72596325b343338cb41c92d9c5b36f65330d379692ca6d6c.png"
+    ],
+    "iris.tests.integration.plot.test_vector_plots.TestBarbs.test_non_latlon_2d_coords.0": [
+        "https://scitools.github.io/test-iris-imagehash/images/v4/a7acb36134d2e676627963259343330cb43e92d9c5336e67330d379292ca6d6c.png"
+    ],
     "iris.tests.integration.plot.test_vector_plots.TestQuiver.test_2d_plain_latlon.0": [
         "https://scitools.github.io/test-iris-imagehash/images/v4/fb8d4f21c472b27e919d2e216f216b3178e69c7e961ab39a84696c616d245b94.png"
     ],

From 7a8808dacc63efdba65c2924b5c2df7ac49f4273 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Thu, 5 Aug 2021 17:05:30 +0000
Subject: [PATCH 15/17] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 lib/iris/tests/integration/plot/test_vector_plots.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/iris/tests/integration/plot/test_vector_plots.py b/lib/iris/tests/integration/plot/test_vector_plots.py
index 03d43c7868..9dad0ddd3b 100644
--- a/lib/iris/tests/integration/plot/test_vector_plots.py
+++ b/lib/iris/tests/integration/plot/test_vector_plots.py
@@ -215,7 +215,7 @@ def _latlon_uv_cubes(grid_cube):
         scale_factor = 30
         u_cube.data *= scale_factor
         v_cube.data *= scale_factor
-        return  u_cube, v_cube
+        return u_cube, v_cube
 
     def plot_function_to_test(self):
         return barbs

From 4e300b40945a0f2baae2b1f45ca9653f20b368ab Mon Sep 17 00:00:00 2001
From: Jon Seddon <17068361+jonseddon@users.noreply.github.com>
Date: Tue, 10 Aug 2021 14:44:11 +0100
Subject: [PATCH 16/17] isort:skip

Co-authored-by: Martin Yeo <40734014+trexfeathers@users.noreply.github.com>
---
 docs/gallery_tests/test_plot_wind_barbs.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/gallery_tests/test_plot_wind_barbs.py b/docs/gallery_tests/test_plot_wind_barbs.py
index 472da0ac53..6003860a5e 100644
--- a/docs/gallery_tests/test_plot_wind_barbs.py
+++ b/docs/gallery_tests/test_plot_wind_barbs.py
@@ -6,7 +6,7 @@
 
 # Import Iris tests first so that some things can be initialised before
 # importing anything else.
-import iris.tests as tests
+import iris.tests as tests  # isort:skip
 
 from .gallerytest_util import (
     add_gallery_to_path,

From d671c2703c2a19673fc1df28090e4f1cae32869c Mon Sep 17 00:00:00 2001
From: Jon Seddon <jon.seddon@metoffice.gov.uk>
Date: Tue, 10 Aug 2021 15:07:57 +0100
Subject: [PATCH 17/17] Docstring note now visible in Sphinx output

---
 lib/iris/plot.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/lib/iris/plot.py b/lib/iris/plot.py
index 27aacdf08e..88202bc7ba 100644
--- a/lib/iris/plot.py
+++ b/lib/iris/plot.py
@@ -1432,7 +1432,7 @@ def barbs(u_cube, v_cube, *args, **kwargs):
         vectors.  The components are aligned with the North and East of the
         cube coordinate system.
 
-    .. Note:
+    .. Note::
 
         At present, if u_cube and v_cube have geographic coordinates, then they
         must be in a lat-lon coordinate system, though it may be a rotated one.
@@ -1480,7 +1480,7 @@ def quiver(u_cube, v_cube, *args, **kwargs):
         vectors.  The components are aligned with the North and East of the
         cube coordinate system.
 
-    .. Note:
+    .. Note::
 
         At present, if u_cube and v_cube have geographic coordinates, then they
         must be in a lat-lon coordinate system, though it may be a rotated one.