csiro-coasts · mx-moth · Dec 16, 2025 · Dec 16, 2025 · Dec 16, 2025 · Dec 16, 2025
diff --git a/README.md b/README.md
@@ -49,6 +49,9 @@ geometry.write_shapefile(dataset, './gbr4.shp')
 
 ## Examples
 
+The `examples/` directory contains examples of making many different plots.
+These are included in the documentation under [Examples][emsarray-examples].
+
 Examples of using `emsarray` are available in the [emsarray-notebooks][emsarray-notebooks] repository.
 You can [explore these notebooks online][emsarray-binder] with Binder.
 
@@ -98,6 +101,7 @@ You can the view the docs at <http://localhost:5500>
 [emsarray-binder]: https://mybinder.org/v2/gh/csiro-coasts/emsarray-notebooks/HEAD
 [emsarray-conda-forge]: https://anaconda.org/conda-forge/emsarray/
 [emsarray-documentation]: https://emsarray.readthedocs.io
+[emsarray-examples]: https://emsarray.readthedocs.io/en/stable/examples/
 [emsarray-notebooks]: https://github.com/csiro-coasts/emsarray-notebooks
 [emsarray-pypi]: https://pypi.org/project/emsarray/
 [emsarray-source-code]: https://github.com/csiro-coasts/emsarray

diff --git a/continuous-integration/docs.yaml b/continuous-integration/docs.yaml
@@ -3,7 +3,9 @@ channels:
 
 dependencies:
   - geos ~=3.12.2
+  - udunits2 >=2.2.25
   - python =3.14
+  - ffmpeg
   - wheel
   - pip:
     - -r ./requirements-3.14.txt

diff --git a/docs/.gitignore b/docs/.gitignore
@@ -1 +1,2 @@
-_build
+_build/
+examples/
diff --git a/docs/_static/images/animated-plot.mp4 b/docs/_static/images/animated-plot.mp4
diff --git a/docs/_static/images/animated-plot.png b/docs/_static/images/animated-plot.png
diff --git a/docs/_static/images/kgari-path.png b/docs/_static/images/kgari-path.png
diff --git a/docs/_static/images/kgari-transect.png b/docs/_static/images/kgari-transect.png
diff --git a/docs/_static/images/plot-set-extent.png b/docs/_static/images/plot-set-extent.png
diff --git a/docs/_static/images/plot-with-clim.png b/docs/_static/images/plot-with-clim.png
diff --git a/docs/api/plot.rst b/docs/api/plot.rst
@@ -11,11 +11,10 @@ The :func:`plot_on_figure` and :func:`animate_on_figure` functions
 will generate a simple plot of any supported variables.
 These functions are intended as quick and simple ways of exploring a dataset
 and have limited customisation options.
-Consult the :ref:`examples gallery <examples>`
-for demonstrations on making more customised plots.
 
-The :ref:`examples <examples>` section contains many worked examples on how to generate plots.
-:ref:`example-plot-with-clim` is a good place to start.
+The :ref:`examples <examples>` section contains many worked examples
+on how to generate plots with more customisations.
+:ref:`sphx_glr_examples_plot-with-clim.py` is a good place to start.
 
 Shortcuts
 =========

diff --git a/docs/api/transect.rst b/docs/api/transect.rst
@@ -12,13 +12,7 @@ Transects are vertical slices along some path through your dataset.
 Examples
 --------
 
-.. list-table::
-
-   * - :ref:`example-kgari-transect`
-
-       .. image:: /_static/images/kgari-transect.png
-          :width: 200
-          :class: no-scaled-link
+.. minigallery:: ../examples/plot-kgari-transect.py
 
 .. autofunction:: plot
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -40,6 +40,7 @@
     'sphinx.ext.intersphinx',
     'sphinx.ext.napoleon',
     'sphinxcontrib.video',
+    'sphinx_gallery.gen_gallery',
     'roles'
 ]
 
@@ -65,9 +66,13 @@
 html_static_path = ['_static']
 
 
-add_module_names = False
+def setup(app):
+    app.add_css_file("hide_links.css")
 
 
+# Options for generated documentation
+add_module_names = True
+
 napoleon_google_docstring = False
 napoleon_numpy_docstring = True
 napoleon_use_param = False
@@ -99,3 +104,13 @@
     'shapely': ('https://shapely.readthedocs.io/en/stable/', None),
     'xarray': ('https://docs.xarray.dev/en/stable/', None),
 }
+
+
+# Sphinx gallery configuration
+sphinx_gallery_conf = {
+    'examples_dirs': '../examples',
+    'gallery_dirs': './examples',
+    'filename_pattern': '/plot-',
+    'matplotlib_animations': True,
+    'backreferences_dir': './examples/backreferences',
+}
diff --git a/docs/examples/animated-plot.rst b/docs/examples/animated-plot.rst
diff --git a/docs/examples/index.rst b/docs/examples/index.rst
diff --git a/docs/examples/kgari-transect.rst b/docs/examples/kgari-transect.rst
diff --git a/docs/examples/plot-set-extent.rst b/docs/examples/plot-set-extent.rst
diff --git a/docs/examples/plot-with-clim.rst b/docs/examples/plot-with-clim.rst
diff --git a/docs/live.py b/docs/live.py
@@ -10,6 +10,7 @@ def main() -> None:
     server.watch('**/*.py', command, delay=0.1)
     server.watch('**/*.ipynb', command, delay=0.1)
     server.watch('../src', command, delay=0.1)
+    server.watch('../examples', command, delay=0.1)
     server.serve(root='./_build/dirhtml')
 
 

diff --git a/docs/releases/0.10.0.rst b/docs/releases/0.10.0.rst
@@ -8,7 +8,7 @@ Released on 2025-09-08
   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>`
+  :ref:`how to set the clim parameter in plots <sphx_glr_examples_plot-with-clim.py>`
   (:pr:`179`).
 * Bumped pinned dependencies (:pr:`183`).
 * Fixed :func:`emsarray.utils.datetime_from_np_time`

diff --git a/docs/releases/development.rst b/docs/releases/development.rst
@@ -2,4 +2,5 @@
 Next release (in development)
 =============================
 
-* ...
+* Add `sphinx-gallery <https://sphinx-gallery.github.io/>`_ to the docs
+  to render the example gallery (:pr:`210`).
diff --git a/examples/GALLERY_HEADER.rst b/examples/GALLERY_HEADER.rst
@@ -0,0 +1,5 @@
+.. _examples:
+
+========
+Examples
+========
diff --git a/docs/examples/animated-plot.py → examples/plot-animation.py b/docs/examples/animated-plot.py → examples/plot-animation.py
@@ -1,3 +1,15 @@
+"""
+=============
+Animated plot
+=============
+
+Animated plots are possible with emsarray by using :class:`matplotlib.animation.FuncAnimation`
+and calling :meth:`.GridArtist.set_data_array()` each frame.
+A :class:`~matplotlib.animation.FuncAnimation` will call a function every frame where you can update the plot.
+Each artist returned by :meth:`.Convention.make_artist()` has a :meth:`~.GridArtist.set_data_array()` method
+which can be used to update the data in the plot.
+In combination this makes animations in emsarray about as straight forward as making a static plot:
+"""
 import cartopy.crs
 import datetime
 import emsarray
@@ -24,7 +36,7 @@
 
 
 # Make a figure
-figure = pyplot.figure(figsize=(8, 8), layout='constrained')
+figure = pyplot.figure(figsize=(8, 8))
 axes = figure.add_subplot(projection=cartopy.crs.PlateCarree())
 axes.set_aspect('equal', adjustable='datalim')
 coast = GSHHSFeature(scale='intermediate')
@@ -47,16 +59,10 @@
     axes, (u.isel(time=0), v.isel(time=0)),
     scale=40)
 
-
-# Finish setting up the plot
-axes.autoscale()
-
-
 def update_plot(frame: int) -> list[Artist]:
     # This function is called every frame and should update the plot with new data.
 
-    # Disable the matplotlib layout engine after the first frame
-    # else the plot has a tendency to jiggle around on later frames.
+    # Disable the layout engine after the first frame, else the plot can shift slightly
     if frame > 0:
         figure.set_layout_engine('none')
 
@@ -72,19 +78,14 @@ def update_plot(frame: int) -> list[Artist]:
     # Return every artist that has been updated this frame
     return [axes.title, magnitude_artist, uv_artist]
 
+# Render the first frame
+update_plot(0)
+
+# Finish setting up the plot
+axes.autoscale()
 
 animation = FuncAnimation(
     figure,  # The figure to animate
     update_plot,  # The function to call to update the plot data
     frames=ds.sizes['time'],  # How many frames of animation to render
 )
-
-# Draw and save the first frame of the animation for a thumbnail
-update_plot(0)
-figure.savefig('animated-plot.png')
-
-# Save the animation
-ffmpeg_writer = FFMpegWriter(fps=5, bitrate=1800)
-animation.save('animated-plot.mp4', writer=ffmpeg_writer)
-
-pyplot.show(block=True)