Add example showing how to set data limits in a plot

docs/examples/index.rst

@@ -30,3 +30,8 @@ Gallery
           :width: 200
           :class: no-scaled-link
 
+   * - :ref:`example-plot-with-clim`
+
+       .. image:: /_static/images/plot-with-clim.png
+          :width: 200
+          :class: no-scaled-link

docs/examples/plot-with-clim.py

@@ -0,0 +1,30 @@
+import cartopy.crs
+import emsarray
+import emsarray.plot
+from cartopy.feature import GSHHSFeature
+from matplotlib import pyplot
+
+ds = emsarray.tutorial.open_dataset('austen')
+
+figure = pyplot.figure(figsize=(10, 8), layout='constrained')
+axes = figure.add_subplot(projection=cartopy.crs.PlateCarree())
+axes.set_aspect('equal', adjustable='datalim')
+
+polys = ds.ems.make_poly_collection(
+    ds['eta'].isel(record=0),
+    clim=(-3, 3), edgecolor='face',
+    cmap='Spectral',
+)
+axes.add_collection(polys)
+figure.colorbar(polys, ax=axes, location='right', label="metres")
+
+coast = GSHHSFeature(scale='intermediate')
+axes.add_feature(coast, facecolor='linen', edgecolor='darkgrey', linewidth=0.5)
+
+axes.autoscale()
+axes.set_title("Sea surface height deviation")
+axes.set_facecolor('aliceblue')
+
+figure.savefig('plot-with-clim.png')
+
+pyplot.show(block=True)

docs/examples/plot-with-clim.rst

@@ -0,0 +1,23 @@
+.. _example-plot-with-clim:
+
+===============================
+Plot with specified data limits
+===============================
+
+The :meth:`Convention.make_poly_collection()` method passes all keyword arguments
+on to :class:`~matplotlib.collections.PolyCollection`.
+This can be used to customise the appearance of the collection
+and to set parameters such as `clim`:
+
+.. image:: /_static/images/plot-with-clim.png
+   :alt: A plot of sea surface height deviation from the Australia wide AUSTEn dataset.
+         The limits of the colour bar have been constrianed to (-3, 3).
+
+Code
+====
+
+:download:`Download plot-with-clim.py example <plot-with-clim.py>`.
+
+.. literalinclude:: plot-with-clim.py
+   :language: python
+

docs/releases/development.rst

@@ -5,3 +5,6 @@ Next release (in development)
 * Fixed issues with detecting topology variables in SHOC datasets
   where some variables are lacking a `standard_name` (:issue:`178`, :pr:`180`).
 * Updated the tests to be compatible with the latest xarray versions (:pr:`182`).
+* Added an example to the documentation showing
+  :ref:`how to set the clim parameter in plots <example-plot-with-clim>`
+  (:pr:`179`).