SciTools · stephenworsley · Jan 28, 2022 · Jan 13, 2022 · Jan 13, 2022 · Jan 13, 2022
diff --git a/docs/src/common_links.inc b/docs/src/common_links.inc
@@ -37,6 +37,7 @@
 .. _test-iris-imagehash: https://github.com/SciTools/test-iris-imagehash
 .. _using git: https://docs.github.com/en/github/using-git
 .. _requirements/ci/: https://github.com/SciTools/iris/tree/main/requirements/ci
+.. _CF-UGRID: https://ugrid-conventions.github.io/ugrid-conventions/
 
 
 .. comment

diff --git a/docs/src/further_topics/index.rst b/docs/src/further_topics/index.rst
@@ -20,6 +20,7 @@ that may be of interest to the more advanced or curious user.
 * :doc:`metadata`
 * :doc:`lenient_metadata`
 * :doc:`lenient_maths`
+* :ref:`ugrid`
 
 
 .. _GitHub Documentation Issue: https://github.com/SciTools/iris/issues/new?assignees=&labels=New%3A+Documentation%2C+Type%3A+Documentation&template=documentation.md&title=

diff --git a/docs/src/further_topics/ugrid/data_model.rst b/docs/src/further_topics/ugrid/data_model.rst
@@ -0,0 +1,29 @@
+.. _ugrid model:
+
+..
+    The conventions page is [necessarily] not for a layperson. This is an
+     opportunity to explain UGRID at an Iris user's level - doesn't need to be
+     exhaustive, just get across what is needed for the user to understand why
+     their experience will be different to 'normal'.
+
+
+The UGRID Data Model
+********************
+
+What's Different?
+=================
+
+..
+    IDEA: The unstructured mesh format maximises flexibility, but means that no
+     spatial information can be inferred from a structured data array. Much
+     less is implicit, much more information has to be stored explicitly.
+
+    Diagram(s) - SVG so editable later.
+
+How Iris Represents This
+========================
+
+..
+    Include API links to the various classes
+
+    Include Cube/Mesh printout(s)
diff --git a/docs/src/further_topics/ugrid/index.rst b/docs/src/further_topics/ugrid/index.rst
@@ -0,0 +1,50 @@
+.. include:: ../../common_links.inc
+
+.. _ugrid:
+
+UGRID Support
+*************
+
+Iris includes specialised handling of data that follows the
+`CF-UGRID Conventions`__. UGRID-conformant data can be loaded from a file,
+represented in Iris' data model, worked with, and saved as a UGRID-conformant
+file. More detail is in this section and in the :mod:`iris.experimental.ugrid`
+API documentation.
+
+----
+
+UGRID is different
+  UGRID's mesh-located data is fundamentally different to grid-located data.
+  Many of Iris' existing operations need adapting before they can work with
+  mesh-located data, and in some cases entirely new concepts are needed.
+  **Read the detail here before jumping into your own code.**
+Iris' UGRID support is experimental
+  This is a rapidly evolving part of the codebase at time of writing
+  (``Jan 2021``), as we continually expand the operations that work with mesh
+  data. **Be prepared for breaking changes even in minor releases.**
+:ref:`Get involved! <development_where_to_start>`
+  We know meshes are an exciting new area for much of Earth science, so we hope
+  there are a lot of you with new files/ideas/wishlists, and we'd love to hear
+  more 🙂.
+
+----
+
+Read on to find out more...
+
+* :doc:`data_model` - learn why the mesh experience is so different.
+* :doc:`partner_packages` - meet some optional dependencies that provide powerful mesh operations.
+* :doc:`operations` - experience how your workflows will look when written for UGRID data.
+
+..
+    Need an actual TOC to get Sphinx working properly, but have hidden it in
+     favour of the custom bullets above.
+
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+
+   data_model
+   partner_packages
+   operations
+
+__ CF-UGRID_
diff --git a/docs/src/further_topics/ugrid/operations.rst b/docs/src/further_topics/ugrid/operations.rst
@@ -0,0 +1,56 @@
+.. _ugrid operations:
+
+Working with UGRID Data
+***********************
+
+.. note:: Several of the operations below rely on the optional dependencies
+          mentioned in :doc:`partner_packages`.
+
+..
+    Have a table here that lists the headings below, including a small note
+     about whether it's unchanged (e.g. Saving), has to be done differently
+     (e.g. Extraction), or isn't yet possible (e.g. Arithmetic). Each row
+     should link to the section below. Basically an enhanced TOC.
+
+..
+    Below: use demo code over prose wherever workable. Headings aren't an
+     exhaustive list (can you think of any other popular operations?).
+
+Load
+----
+
+Summary
+-------
+..
+    Possibly covered by the data_model page?
+
+Save
+----
+
+Plotting
+--------
+
+Regional Extraction
+-------------------
+..
+    Highlight the uselessness of indexing.
+
+Regridding
+----------
+
+Equality
+--------
+..
+    Is this worth mentioning, given it just works the way it always has?
+
+Recombination
+-------------
+
+Arithmetic
+----------
+..
+    Not possible yet - mention this.
+
+..
+    Headings for other popular operations that aren't yet possible, including
+     if they're planned soon.
diff --git a/docs/src/further_topics/ugrid/partner_packages.rst b/docs/src/further_topics/ugrid/partner_packages.rst
@@ -0,0 +1,17 @@
+.. _ugrid partners:
+
+..
+    * Explain the optional GeoVista and iris-esmf-regrid dependencies, which
+       are powerful but big and should only be installed if the user needs
+       them.
+    * Brief description of each, and when you might use it.
+    * Link to docs if applicable (intersphinx?).
+
+Iris' UGRID Partner Packages
+****************************
+
+GeoVista
+========
+
+iris-esmf-regrid
+================
diff --git a/docs/src/index.rst b/docs/src/index.rst
@@ -131,6 +131,7 @@ For **Iris 2.4** and earlier documentation please see the
    further_topics/metadata
    further_topics/lenient_metadata
    further_topics/lenient_maths
+   further_topics/ugrid/index
 
 
 .. toctree::

diff --git a/docs/src/whatsnew/latest.rst b/docs/src/whatsnew/latest.rst
@@ -16,7 +16,7 @@ This document explains the changes made to Iris for this release
 
    The highlights for this minor release of Iris include:
 
-   * We've added experimental support for `UGRID`_ meshes which can now be loaded
+   * We've added experimental support for `CF-UGRID`_ meshes which can now be loaded
      and attached to a cube.
    * We've also dropped support for ``Python 3.7``.
 
@@ -37,7 +37,7 @@ This document explains the changes made to Iris for this release
 ===========
 
 #. `@bjlittle`_, `@pp-mo`_, `@trexfeathers`_ and `@stephenworsley`_ added
-   support for unstructured meshes, as described by `UGRID`_. This involved
+   support for unstructured meshes, as described by `CF-UGRID`_. This involved
    adding a data model (:pull:`3968`, :pull:`4014`, :pull:`4027`, :pull:`4036`,
    :pull:`4053`, :pull:`4439`) and API (:pull:`4063`, :pull:`4064`), and
    supporting representation (:pull:`4033`, :pull:`4054`) of data on meshes.
@@ -54,14 +54,14 @@ This document explains the changes made to Iris for this release
    :class:`~iris.cube.Cube` via a :class:`~iris.experimental.ugrid.mesh.MeshCoord`.
 
 #. `@trexfeathers`_ added support for loading unstructured mesh data from netcdf data,
-   for files using the `UGRID`_ conventions.
+   for files using the `CF-UGRID`_ conventions.
    The context manager :obj:`~iris.experimental.ugrid.load.PARSE_UGRID_ON_LOAD`
    provides a way to load UGRID files so that :class:`~iris.cube.Cube`\ s can be
    returned with a :class:`~iris.experimental.ugrid.mesh.Mesh` attached.
    (:pull:`4058`).
 
 #. `@pp-mo`_ added support to save cubes with meshes to netcdf files, using the
-   `UGRID`_ conventions.
+   `CF-UGRID`_ conventions.
    The existing :meth:`iris.save` function now does this, when saving cubes with meshes.
    A routine :meth:`iris.experimental.ugrid.save.save_mesh` allows saving
    :class:`~iris.experimental.ugrid.mesh.Mesh` objects to netcdf *without* any associated data
@@ -82,7 +82,7 @@ This document explains the changes made to Iris for this release
    :class:`~iris.coords.AuxCoord` :attr:`~iris.coords.AuxCoord.points` and
    :class:`~iris.experimental.ugrid.mesh.Connectivity`
    :attr:`~iris.experimental.ugrid.mesh.Connectivity.indices` under the
-   `UGRID`_ model. (:pull:`4375`)
+   `CF-UGRID`_ model. (:pull:`4375`)
 
 #. `@bsherratt`_ added a `threshold` parameter to
    :meth:`~iris.cube.Cube.intersection` (:pull:`4363`)
@@ -271,7 +271,7 @@ This document explains the changes made to Iris for this release
    :func:`~iris.analysis.cartography.wrap_lons` and updated affected tests
    using assertArrayAllClose following :issue:`3993`.
    (:pull:`4421`)
-   
+
 #. `@rcomer`_ updated some tests to work with Matplotlib v3.5. (:pull:`4428`)
 
 #. `@rcomer`_ applied minor fixes to some regridding tests. (:pull:`4432`)
@@ -304,7 +304,6 @@ This document explains the changes made to Iris for this release
 
 .. _GitHub: https://github.com/SciTools/iris/issues/new/choose
 .. _NEP-29: https://numpy.org/neps/nep-0029-deprecation_policy.html
-.. _UGRID: http://ugrid-conventions.github.io/ugrid-conventions/
 .. _sort-all: https://github.com/aio-libs/sort-all
 .. _faster documentation building: https://docs.readthedocs.io/en/stable/guides/conda.html#making-builds-faster-with-mamba
 .. _Metarelate: http://www.metarelate.net/