[FB] [PI-3478] Metadata and cube maths documentation

docs/iris/src/conf.py

@@ -271,3 +271,15 @@ def autolog(message):
     message="Matplotlib is currently using agg, which is a"
     " non-GUI backend, so cannot show the figure.",
 )
+
+
+# -- numfig options (built-in) ------------------------------------------------
+# Enable numfig.
+numfig = True
+
+numfig_format = {
+    "code-block": "Example %s",
+    "figure": "Figure %s",
+    "section": "Section %s",
+    "table": "Table %s",
+}

docs/iris/src/index.rst

@@ -69,6 +69,7 @@ Iris is part of SciTools, for more information see https://scitools.org.uk/.
    userguide/interpolation_and_regridding
    userguide/merge_and_concat
    userguide/cube_statistics
+   userguide/metadata
    userguide/cube_maths
    userguide/citation
    userguide/code_maintenance

docs/iris/src/userguide/saving_iris_cubes.rst

@@ -44,6 +44,8 @@ Controlling the save process
 
 The :py:func:`iris.save` function passes all other keywords through to the saver function defined, or automatically set from the file extension.  This enables saver specific functionality to be called.
 
+.. doctest::
+
     >>> # Save a cube to PP
     >>> iris.save(cubes[0], "myfile.pp")
     >>> # Save a cube list to a PP file, appending to the contents of the file
@@ -54,6 +56,16 @@ The :py:func:`iris.save` function passes all other keywords through to the saver
     >>> # Save a cube list to netCDF, using the NETCDF3_CLASSIC storage option
     >>> iris.save(cubes, "myfile.nc", netcdf_format="NETCDF3_CLASSIC")
 
+.. testcleanup::
+
+    import pathlib
+    p = pathlib.Path("myfile.pp")
+    if p.exists():
+        p.unlink()
+    p = pathlib.Path("myfile.nc")
+    if p.exists():
+        p.unlink()
+
 See 
 
 * :py:func:`iris.fileformats.netcdf.save`

lib/iris/common/metadata.py

@@ -654,6 +654,21 @@ def equal(self, other, lenient=None):
 
     @classmethod
     def from_metadata(cls, other):
+        """
+        Convert the provided metadata instance from a different type
+        to this metadata type, using only the relevant metadata members.
+
+        Non-common metadata members as set to ``None``.
+
+        Args:
+
+        * other (metadata):
+            A metadata instance of any type.
+
+        Returns:
+            New metadata instance.
+
+        """
         result = None
         if isinstance(other, BaseMetadata):
             if other.__class__ is cls:

lib/iris/common/resolve.py

@@ -115,6 +115,7 @@ class Resolve:
                   source: Data from Met Office Unified Model 6.05
              Cell methods:
                   mean: time (6 hour)
+
         >>> print(cube2)
         air_temperature / (K)               (longitude: 49; latitude: 37)
              Dimension coordinates:
@@ -132,6 +133,7 @@ class Resolve:
                   source: Data from Met Office Unified Model 6.05
              Cell methods:
                   mean: time (6 hour)
+
         >>> print(data.shape)
         (240, 37, 49)
         >>> resolver = Resolve(cube1, cube2)
@@ -203,7 +205,7 @@ def __init__(self, lhs=None, rhs=None):
             but this may not be possible when auto-transposition or extended broadcasting
             is involved during the operation.
 
-        For example,
+        For example:
 
         .. doctest::
 
@@ -1681,33 +1683,33 @@ def cube(self, data, in_place=False):
             match** the expected resolved
             :attr:`~iris.common.resolve.Resolve.shape`.
 
-        For example,
+        For example:
 
-        .. testsetup::
+        .. testsetup:: in-place
 
             import iris
             import numpy as np
             from iris.common import Resolve
-            tgt = iris.load_cube(iris.sample_data_path("A1B_north_america.nc"))
-            src = iris.load_cube(iris.sample_data_path("E1_north_america.nc"))[0]
-            src.transpose()
-            zeros = np.zeros(tgt.shape, dtype=tgt.dtype)
+            cube1 = iris.load_cube(iris.sample_data_path("A1B_north_america.nc"))
+            cube2 = iris.load_cube(iris.sample_data_path("E1_north_america.nc"))[0]
+            cube2.transpose()
+            zeros = np.zeros(cube1.shape, dtype=cube1.dtype)
 
-        .. doctest::
+        .. doctest:: in-place
 
-            >>> resolver = Resolve(tgt, src)
+            >>> resolver = Resolve(cube1, cube2)
             >>> resolver.map_rhs_to_lhs
             True
-            >>> tgt.data.sum()
+            >>> cube1.data.sum()
             124652160.0
             >>> zeros.shape
             (240, 37, 49)
             >>> zeros.sum()
             0.0
             >>> result = resolver.cube(zeros, in_place=True)
-            >>> result is tgt
+            >>> result is cube1
             True
-            >>> tgt.data.sum()
+            >>> cube1.data.sum()
             0.0
 
         """
@@ -1826,7 +1828,7 @@ def mapped(self):
         If no :class:`~iris.cube.Cube` operands have been provided, then
         ``mapped`` is ``None``.
 
-        For example,
+        For example:
 
         .. doctest::
 
@@ -1894,7 +1896,7 @@ def shape(self):
         If no :class:`~iris.cube.Cube` operands have been provided, then
         ``shape`` is ``None``.
 
-        For example,
+        For example:
 
         .. doctest::
 

lib/iris/coords.py

@@ -2354,10 +2354,10 @@ def __init__(
             Descriptive name of the coordinate.
         * var_name:
             The netCDF variable name for the coordinate.
-        * units
+        * units:
             The :class:`~cf_units.Unit` of the coordinate's values.
             Can be a string, which will be converted to a Unit object.
-        * bounds
+        * bounds:
             An array of values describing the bounds of each cell. Given n
             bounds and m cells, the shape of the bounds array should be
             (m, n). For each bound, the values must be strictly monotonic along
@@ -2368,15 +2368,15 @@ def __init__(
             in the same direction.  Masked values are not allowed.
             Note if the data is a climatology, `climatological`
             should be set.
-        * attributes
+        * attributes:
             A dictionary containing other cf and user-defined attributes.
-        * coord_system
+        * coord_system:
             A :class:`~iris.coord_systems.CoordSystem` representing the
             coordinate system of the coordinate,
             e.g. a :class:`~iris.coord_systems.GeogCS` for a longitude Coord.
-        * circular (bool)
-            For units with a modulus (e.g. degrees), do the points wrap around
-            the full circle?
+        * circular (bool):
+            Whether the coordinate wraps by the :attr:`~iris.coords.DimCoord.units.modulus`
+            i.e., the longitude coordinate wraps around the full great circle.
         * climatological (bool):
             When True: the coordinate is a NetCDF climatological time axis.
             When True: saving in NetCDF will give the coordinate variable a