Document Coord.ignore_axis (#5744)

* Document Coord.ignore_axis.

* What's New entry.

docs/src/further_topics/netcdf_io.rst

@@ -134,7 +134,49 @@ Deferred Saving
 TBC
 
 
-Guess Axis
------------
-
-TBC
+Guessing Coordinate Axes
+------------------------
+
+Iris will attempt to add an ``axis`` attribute when saving any coordinate
+variable in a NetCDF file. E.g:
+
+::
+
+    float longitude(longitude) ;
+        longitude:axis = "X" ;
+
+This is achieved by calling :func:`iris.util.guess_coord_axis` on each
+coordinate being saved.
+
+Disabling Axis-Guessing
+^^^^^^^^^^^^^^^^^^^^^^^
+
+For some coordinates, :func:`~iris.util.guess_coord_axis` will derive an
+axis that is not appropriate. If you have such a coordinate, you can disable
+axis-guessing by setting the coordinate's
+:attr:`~iris.coords.Coord.ignore_axis` property to ``True``.
+
+One example (from https://github.com/SciTools/iris/issues/5003) is a
+coordinate describing pressure thresholds, measured in hecto-pascals.
+Iris interprets pressure units as indicating a Z-dimension coordinate, since
+pressure is most commonly used to describe altitude/depth. But a
+**pressure threshold** coordinate is instead describing alternate
+**scenarios** - not a spatial dimension at all - and it is therefore
+inappropriate to assign an axis to it.
+
+Worked example:
+
+.. doctest::
+
+    >>> from iris.coords import DimCoord
+    >>> from iris.util import guess_coord_axis
+    >>> my_coord = DimCoord(
+    ...    points=[1000, 1010, 1020],
+    ...    long_name="pressure_threshold",
+    ...    units="hPa",
+    ... )
+    >>> print(guess_coord_axis(my_coord))
+    Z
+    >>> my_coord.ignore_axis = True
+    >>> print(guess_coord_axis(my_coord))
+    None

docs/src/whatsnew/latest.rst

@@ -61,7 +61,7 @@ This document explains the changes made to Iris for this release
 
 #. `@HGWright`_ added :attr:`~iris.coords.Coord.ignore_axis` to allow manual
    intervention preventing :func:`~iris.util.guess_coord_axis` from acting on a
-   coordinate. (:pull:`5551`)
+   coordinate. `@trexfeathers`_ documented this. (:pull:`5551`, :pull:`5744`)
 
 #. `@pp-mo`_, `@trexfeathers`_ and `@ESadek-MO`_ added more control over
    NetCDF chunking with the use of the :data:`iris.fileformats.netcdf.loader.CHUNK_CONTROL`
@@ -234,7 +234,7 @@ This document explains the changes made to Iris for this release
 #. `@bjlittle`_ replaced `black`_ with `ruff`_. (:pull:`5634`)
 
 #. `@tkknight`_ and `@bjlittle`_ (reviewer) updated codebase to be compliant with
-   almost all of the rules for `ruff pydocstyle`_. 
+   almost all of the rules for `ruff pydocstyle`_.
    (https://github.com/SciTools/iris/issues/5625#issuecomment-1859159734)
 
 #. `@tkknight`_ and `@bjlittle`_ (reviewer) updated codebase to ensure docstrings

lib/iris/coords.py

@@ -1662,10 +1662,10 @@ def climatological(self, value):
 
     @property
     def ignore_axis(self):
-        """A boolean that controls whether guess_coord_axis acts on this coordinate.
+        """A boolean controlling if iris.util.guess_coord_axis acts on this coordinate.
 
-        Defaults to False, and when set to True it will be skipped by
-        guess_coord_axis.
+        Defaults to ``False``, and when set to ``True`` it will be skipped by
+        :func:`iris.util.guess_coord_axis`.
         """
         return self._ignore_axis
 

lib/iris/util.py

@@ -249,8 +249,8 @@ def guess_coord_axis(coord):
     This function maintains laziness when called; it does not realise data.
     See more at :doc:`/userguide/real_and_lazy_data`.
 
-    The ``guess_coord_axis`` behaviour can be skipped by setting the coordinate
-    property ``ignore_axis`` to ``False``.
+    The ``guess_coord_axis`` behaviour can be skipped by setting the
+    :attr:`~iris.coords.Coord.ignore_axis` property on `coord` to ``False``.
 
     """
     axis = None