SciTools · trexfeathers · Dec 12, 2025 · Dec 19, 2025 · Dec 30, 2025 · Dec 30, 2025
diff --git a/.lycheeignore b/.lycheeignore
@@ -4,16 +4,17 @@ file:///
 # DEAD : legacy in various old whatsnews
 https://biggus.readthedocs.io
 
-# unkown problem, works in browser : used in further_topics/ugrid/data_model
+# unknown problem, works in browser : used in
+#  docs/src/user_manual/explanation/mesh_data_model.rst
 https://doi.org/10.3390/jmse2010194
 
-# DEAD, todo:remove, used in docs/src/userguide/plotting_a_cube.rst
+# DEAD, todo:remove, used in docs/src/user_manual/tutorial/plotting_a_cube.rst
 https://effbot.org
 
 # nonfunctional, found in some code examples
 https://foo/
 
-# DEAD, todo:remove, used in docs/src/further_topics/ugrid/data_model.rst
+# DEAD, todo:remove, used in docs/src/user_manual/explanation/mesh_data_model.rst
 https://ibm-design-language.eu-de.mybluemix.net/design/language/resources/color-library
 
 # DEAD, legacy in whatsnew/1.4.rst
@@ -45,14 +46,14 @@ https://stickler-ci.com
 # DEAD, todo:remove, used in lib/iris/symbols.py
 https://www.wmo.int/pages/prog/www/DPFS/documents/485_Vol_I_en_colour.pdf
 
-# DEAD, todo:remove, used in docs/src/userguide/plotting_a_cube.rst
+# DEAD, todo:remove, used in docs/src/user_manual/tutorial/plotting_a_cube.rst
 # unkown problem, works in browser : used in docs/src/index.rst
 https://www.flaticon.com
 
 # nonfunctional example, used in lib/iris/io/__init__.py
 https://www.thing.com
 
-# DEAD, todo:remove, used in docs/src/userguide/plotting_a_cube.rst
+# DEAD, todo:remove, used in docs/src/user_manual/tutorial/plotting_a_cube.rst
 https://www.personal.psu.edu/cab38/ColorBrewer/ColorBrewer_updates.html
 
 # nonfunctional, found in some code examples

diff --git a/docs/gallery_code/general/plot_SOI_filtering.py b/docs/gallery_code/general/plot_SOI_filtering.py
@@ -2,6 +2,11 @@
 Applying a Filter to a Time-Series
 ==================================
 
+.. how-to:: Applying a Filter to a Time-Series
+   :tags: topic_plotting;topic_statistics
+
+   How to use custom NumPy code for filtering an Iris Cube.
+
 This example demonstrates low pass filtering a time-series by applying a
 weighted running mean over the time dimension.
 

diff --git a/docs/gallery_code/general/plot_anomaly_log_colouring.py b/docs/gallery_code/general/plot_anomaly_log_colouring.py
@@ -2,6 +2,11 @@
 Colouring Anomaly Data With Logarithmic Scaling
 ===============================================
 
+.. how-to:: Colouring Anomaly Data With Logarithmic Scaling
+   :tags: topic_plotting;topic_statistics
+
+   How to visualise logarithmic values.
+
 In this example, we need to plot anomaly data where the values have a
 "logarithmic" significance  -- i.e. we want to give approximately equal ranges
 of colour between data values of, say, 1 and 10 as between 10 and 100.

diff --git a/docs/gallery_code/general/plot_coriolis.py b/docs/gallery_code/general/plot_coriolis.py
@@ -2,6 +2,11 @@
 Deriving the Coriolis Frequency Over the Globe
 ==============================================
 
+.. how-to:: Deriving the Coriolis Frequency Over the Globe
+   :tags: topic_plotting;topic_data_model
+
+   How to create your own Cube from computed data and visualise it.
+
 This code computes the Coriolis frequency and stores it in a cube with
 associated metadata. It then plots the Coriolis frequency on an orthographic
 projection.

diff --git a/docs/gallery_code/general/plot_cross_section.py b/docs/gallery_code/general/plot_cross_section.py
@@ -2,6 +2,11 @@
 Cross Section Plots
 ===================
 
+.. how-to:: Cross Section Plots
+   :tags: topic_plotting;topic_data_model
+
+   How to visualise cross-sections of multi-dimensional Cubes.
+
 This example demonstrates contour plots of a cross-sectioned multi-dimensional
 cube which features a hybrid height vertical coordinate system.
 

diff --git a/docs/gallery_code/general/plot_custom_aggregation.py b/docs/gallery_code/general/plot_custom_aggregation.py
@@ -2,6 +2,11 @@
 Calculating a Custom Statistic
 ==============================
 
+.. how-to:: Calculating a Custom Statistic
+   :tags: topic_plotting;topic_statistics
+
+   How to define and use a custom aggregation operation, including visualisation.
+
 This example shows how to define and use a custom
 :class:`iris.analysis.Aggregator`, that provides a new statistical operator for
 use with cube aggregation functions such as :meth:`~iris.cube.Cube.collapsed`,

diff --git a/docs/gallery_code/general/plot_custom_file_loading.py b/docs/gallery_code/general/plot_custom_file_loading.py
@@ -2,6 +2,11 @@
 Loading a Cube From a Custom File Format
 ========================================
 
+.. how-to:: Loading a Cube From a Custom File Format
+   :tags: topic_plotting;topic_load_save
+
+   How to visualise data from a file Iris does not natively support.
+
 This example shows how a custom text file can be loaded using the standard Iris
 load mechanism.
 

diff --git a/docs/gallery_code/general/plot_global_map.py b/docs/gallery_code/general/plot_global_map.py
@@ -2,6 +2,11 @@
 Quickplot of a 2D Cube on a Map
 ===============================
 
+.. how-to:: Quickplot of a 2D Cube on a Map
+   :tags: topic_plotting
+
+   Code demonstrating basic iris.quickplot use.
+
 This example demonstrates a contour plot of global air temperature. The plot
 title and the labels for the axes are automatically derived from the metadata.
 

diff --git a/docs/gallery_code/general/plot_inset.py b/docs/gallery_code/general/plot_inset.py
@@ -2,6 +2,11 @@
 Test Data Showing Inset Plots
 =============================
 
+.. how-to:: Test Data Showing Inset Plots
+   :tags: topic_plotting;topic_statistics
+
+   How to create inset plots within a main plot; often used to show statistical collapses.
+
 This example demonstrates the use of a single 3D data cube with time, latitude
 and longitude dimensions to plot a temperature series for a single latitude
 coordinate, with an inset plot of the data region.

diff --git a/docs/gallery_code/general/plot_lineplot_with_legend.py b/docs/gallery_code/general/plot_lineplot_with_legend.py
@@ -2,6 +2,11 @@
 Multi-Line Temperature Profile Plot
 ===================================
 
+.. how-to:: Multi-Line Temperature Profile Plot
+   :tags: topic_plotting
+
+   How to plot multiple lines on a single plot with a legend.
+
 """  # noqa: D205, D212, D400
 
 import matplotlib.pyplot as plt

diff --git a/docs/gallery_code/general/plot_polar_stereo.py b/docs/gallery_code/general/plot_polar_stereo.py
@@ -2,6 +2,11 @@
 Example of a Polar Stereographic Plot
 =====================================
 
+.. how-to:: Example of a Polar Stereographic Plot
+   :tags: topic_plotting
+
+   How to visualise data defined on an alternative map projection.
+
 Demonstrates plotting data that are defined on a polar stereographic
 projection.
 

diff --git a/docs/gallery_code/general/plot_polynomial_fit.py b/docs/gallery_code/general/plot_polynomial_fit.py
@@ -2,6 +2,11 @@
 Fitting a Polynomial
 ====================
 
+.. how-to:: Fitting a Polynomial
+   :tags: topic_plotting;topic_statistics;topic_data_model
+
+   How to compute and plot a polynomial fit to 1D data in an Iris cube.
+
 This example demonstrates computing a polynomial fit to 1D data from an Iris
 cube, adding the fit to the cube's metadata, and plotting both the 1D data and
 the fit.

diff --git a/docs/gallery_code/general/plot_projections_and_annotations.py b/docs/gallery_code/general/plot_projections_and_annotations.py
@@ -2,6 +2,11 @@
 Plotting in Different Projections
 =================================
 
+.. how-to:: Plotting in Different Projections
+   :tags: topic_plotting;topic_interoperability
+
+   How to overlay data and graphics in different map projections.
+
 This example shows how to overlay data and graphics in different projections,
 demonstrating various features of Iris, Cartopy and matplotlib.
 

diff --git a/docs/gallery_code/general/plot_rotated_pole_mapping.py b/docs/gallery_code/general/plot_rotated_pole_mapping.py
@@ -2,6 +2,11 @@
 Rotated Pole Mapping
 ====================
 
+.. how-to:: Rotated Pole Mapping
+   :tags: topic_plotting
+
+   How to visualise data defined on an alternative coordinate system.
+
 This example uses several visualisation methods to achieve an array of
 differing images, including:
 

diff --git a/docs/gallery_code/general/plot_zonal_means.py b/docs/gallery_code/general/plot_zonal_means.py
@@ -2,6 +2,11 @@
 Zonal Mean Diagram of Air Temperature
 =====================================
 
+.. how-to:: Zonal Mean Diagram of Air Temperature
+   :tags: topic_plotting;topic_statistics
+
+   How to use aligned plots to visualise collapsed dimensional statistics.
+
 This example demonstrates aligning a linear plot and a cartographic plot
 using Matplotlib.
 

diff --git a/docs/gallery_code/meteorology/plot_COP_1d.py b/docs/gallery_code/meteorology/plot_COP_1d.py
@@ -2,6 +2,11 @@
 Global Average Annual Temperature Plot
 ======================================
 
+.. how-to:: Global Average Annual Temperature Plot
+   :tags: topic_plotting;topic_data_model;topic_statistics
+
+   How to spatially constrain data, compute statistics and visualise a comparison.
+
 Produces a time-series plot of North American temperature forecasts for 2
 different emission scenarios. Constraining data to a limited spatial area also
 features in this example.

diff --git a/docs/gallery_code/meteorology/plot_COP_maps.py b/docs/gallery_code/meteorology/plot_COP_maps.py
@@ -2,6 +2,11 @@
 Global Average Annual Temperature Maps
 ======================================
 
+.. how-to:: Global Average Annual Temperature Maps
+   :tags: topic_plotting
+
+   How to produce comparative maps of two files with a shared colour bar.
+
 Produces maps of global temperature forecasts from the A1B and E1 scenarios.
 
 The data used comes from the HadGEM2-AO model simulations for the A1B and E1

diff --git a/docs/gallery_code/meteorology/plot_TEC.py b/docs/gallery_code/meteorology/plot_TEC.py
@@ -2,6 +2,11 @@
 Ionosphere Space Weather
 ========================
 
+.. how-to:: Ionosphere Space Weather
+   :tags: topic_plotting
+
+   How to use Iris to visualise space weather data.
+
 This space weather example plots a filled contour of rotated pole point
 data with a shaded relief image underlay. The plot shows aggregated
 vertical electron content in the ionosphere.

diff --git a/docs/gallery_code/meteorology/plot_deriving_phenomena.py b/docs/gallery_code/meteorology/plot_deriving_phenomena.py
@@ -2,6 +2,11 @@
 Deriving Exner Pressure and Air Temperature
 ===========================================
 
+.. how-to:: Deriving Exner Pressure and Air Temperature
+   :tags: topic_plotting;topic_statistics
+
+   How to use Iris arithmetic to derive phenomena from existing cubes and plot them.
+
 This example shows some processing of cubes in order to derive further related
 cubes; in this case the derived cubes are Exner pressure and air temperature
 which are calculated by combining air pressure, air potential temperature and

diff --git a/docs/gallery_code/meteorology/plot_hovmoller.py b/docs/gallery_code/meteorology/plot_hovmoller.py
@@ -2,6 +2,11 @@
 Hovmoller Diagram of Monthly Surface Temperature
 ================================================
 
+.. how-to:: Hovmoller Diagram of Monthly Surface Temperature
+   :tags: topic_plotting;topic_statistics
+
+   How to collapse and plot Cubes to create a Hovmoller diagram.
+
 This example demonstrates the creation of a Hovmoller diagram with fine control
 over plot ticks and labels. The data comes from the Met Office OSTIA project
 and has been pre-processed to calculate the monthly mean sea surface

diff --git a/docs/gallery_code/meteorology/plot_lagged_ensemble.py b/docs/gallery_code/meteorology/plot_lagged_ensemble.py
@@ -2,6 +2,11 @@
 Seasonal Ensemble Model Plots
 =============================
 
+.. how-to:: Seasonal Ensemble Model Plots
+   :tags: topic_plotting;topic_data_model;topic_statistics
+
+   How to use Iris in a real-world complex analysis scenario.
+
 This example demonstrates the loading of a lagged ensemble dataset from the
 GloSea4 model, which is then used to produce two types of plot:
 

diff --git a/docs/gallery_code/meteorology/plot_wind_barbs.py b/docs/gallery_code/meteorology/plot_wind_barbs.py
@@ -2,6 +2,11 @@
 Plotting Wind Direction Using Barbs
 ===================================
 
+.. how-to:: Plotting Wind Direction Using Barbs
+   :tags: topic_plotting;topic_statistics
+
+   How to use Iris to derive and plot wind 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.

diff --git a/docs/gallery_code/meteorology/plot_wind_speed.py b/docs/gallery_code/meteorology/plot_wind_speed.py
@@ -2,6 +2,11 @@
 Plotting Wind Direction Using Quiver
 ====================================
 
+.. how-to:: Plotting Wind Direction Using Quiver
+   :tags: topic_plotting
+
+   How to use Iris to plot wind quivers.
+
 This example demonstrates using quiver to plot wind speed contours and wind
 direction arrows from wind vector component input data. The vector components
 are co-located in space in this case.

diff --git a/docs/gallery_code/oceanography/plot_atlantic_profiles.py b/docs/gallery_code/oceanography/plot_atlantic_profiles.py
@@ -2,6 +2,11 @@
 Oceanographic Profiles and T-S Diagrams
 =======================================
 
+.. how-to:: Oceanographic Profiles and T-S Diagrams
+   :tags: topic_plotting;topic_data_model
+
+   How to use Iris for visualising oceanographic profile data.
+
 This example demonstrates how to plot vertical profiles of different
 variables in the same axes, and how to make a scatter plot of two
 variables. There is an oceanographic theme but the same techniques are

diff --git a/docs/gallery_code/oceanography/plot_load_nemo.py b/docs/gallery_code/oceanography/plot_load_nemo.py
@@ -2,6 +2,11 @@
 Load a Time Series of Data From the NEMO Model
 ==============================================
 
+.. how-to:: Load a Time Series of Data From the NEMO Model
+   :tags: topic_plotting;topic_load_save;topic_data_model
+
+   How to combine and visualise multiple files.
+
 This example demonstrates how to load multiple files containing data output by
 the NEMO model and combine them into a time series in a single cube. The
 different time dimensions in these files can prevent Iris from concatenating

diff --git a/docs/gallery_code/oceanography/plot_orca_projection.py b/docs/gallery_code/oceanography/plot_orca_projection.py
@@ -2,6 +2,11 @@
 Tri-Polar Grid Projected Plotting
 =================================
 
+.. how-to:: Tri-Polar Grid Projected Plotting
+   :tags: topic_plotting
+
+   How to visualise data defined on a tri-polar grid using different map projections.
+
 This example demonstrates cell plots of data on the semi-structured ORCA2 model
 grid.