[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/further_topics/index.rst

@@ -0,0 +1,24 @@
+Introduction
+============
+
+Some specific areas of Iris may required further explanation or a deep dive
+into additional detail above and beyond that offered by the
+:ref:`User guide <user_guide_introduction>`.
+
+This section provides a collection of additional material on focused topics
+that may be of interest to the more advanced or curious user.
+
+.. hint::
+
+   If you wish further documentation on any specific topics or areas of Iris
+   that are missing, then please let us know by raising a `GitHub Documentation Issue`_
+   on `SciTools/Iris`_.
+
+
+* :doc:`metadata`
+* :doc:`lenient_metadata`
+* :doc:`lenient_maths`
+
+
+.. _GitHub Documentation Issue: https://github.com/SciTools/iris/issues/new?assignees=&labels=New%3A+Documentation%2C+Type%3A+Documentation&template=documentation.md&title=
+.. _SciTools/iris: https://github.com/SciTools/iris

docs/iris/src/further_topics/lenient_maths.rst

@@ -0,0 +1,9 @@
+.. _lenient maths:
+
+******************
+Lenient cube maths
+******************
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean vitae tortor maximus, suscipit sapien ut, consequat ante. Pellentesque lacinia efficitur neque, sit amet ultricies libero pharetra sit amet. Ut nisl magna, finibus nec dictum quis, eleifend aliquam justo. Aenean sed quam diam. In iaculis felis a odio vulputate, placerat pretium arcu elementum. Quisque commodo et eros id pellentesque. Quisque aliquam tortor eu ex mollis, sit amet pretium sapien vestibulum. Aenean fermentum metus velit, vitae dignissim urna aliquam sed. Etiam laoreet sit amet felis eget ullamcorper.
+
+Vestibulum vitae lacinia quam. Quisque urna nunc, vehicula quis eleifend sed, interdum quis est. Nulla non facilisis dolor. Sed eros augue, tempus mollis leo quis, porta auctor neque. Ut id nisl turpis. Suspendisse feugiat imperdiet neque a ultrices. Proin ut venenatis felis. Aliquam erat volutpat. Mauris finibus, mauris quis volutpat pulvinar, ligula lectus rhoncus turpis, vitae luctus ex mi non felis. Interdum et malesuada fames ac ante ipsum primis in faucibus. Fusce velit turpis, semper ut augue eu, maximus mattis nunc. Integer venenatis nisl et luctus porta. Morbi ipsum massa, volutpat nec placerat a, iaculis vel sem. Proin eleifend in felis vitae pulvinar.

docs/iris/src/further_topics/lenient_metadata.rst

@@ -0,0 +1,80 @@
+.. _lenient metadata:
+
+****************
+Lenient metadata
+****************
+
+As discussed in :ref:`metadata`, a rich, common metadata API is available within
+Iris that supports metadata :ref:`equality <metadata equality>`,
+:ref:`difference <metadata difference>`, :ref:`combination <metadata combine>`,
+and also :ref:`conversion <metadata conversion>`.
+
+The common metadata API is implemented through the ``metadata`` property
+on each of the Iris `CF Conventions`_ class containers in
+:numref:`metadata classes table`, and provides a common gateway for users to
+easily manage and manipulate their metadata in a consistent and unified way.
+
+This is primarily all thanks to the metadata classes (:numref:`metadata classes table`)
+that support the necessary state and behaviour required by the common metadata
+API. Namely, it is the ``equal`` (``__eq__``), ``difference`` and
+``combine`` methods that provide this rich metadata behaviour, all of which are
+explored more fully in :ref:`metadata`.
+
+In particular, the feature that is common between the ``equal``, ``difference``
+and ``combine`` methods, is that they all perform **strict** metadata member
+comparisons by default.
+
+This **strict** behaviour of these methods can be summarised as follows,
+where ``X`` and ``Y`` are any object that are non-identical,
+
+.. _strict equality table:
+.. table:: - Strict equality
+   :widths: auto
+   :align: center
+
+   ======== ======== ==========
+   left     right    **__eq__**
+   ======== ======== ==========
+   ``X``    ``Y``    ``False``
+   ``Y``    ``X``    ``False``
+   ``X``    ``X``    ``True``
+   ``X``    ``None`` ``False``
+   ``None`` ``X``    ``False``
+   ======== ======== ==========
+
+.. _strict difference table:
+.. table:: - Strict difference
+   :widths: auto
+   :align: center
+
+   ======== ======== =================
+   left     right    **__eq__**
+   ======== ======== =================
+   ``X``    ``Y``    (``X``, ``Y``)
+   ``Y``    ``X``    (``Y``, ``X``)
+   ``X``    ``X``    ``None``
+   ``X``    ``None`` (``X``, ``None``)
+   ``None`` ``X``    (``None``, ``X``)
+   ======== ======== =================
+
+.. _strict combine table:
+.. table:: - Strict combination
+   :widths: auto
+   :align: center
+
+   ======== ======== ==========
+   left     right    **__eq__**
+   ======== ======== ==========
+   ``X``    ``Y``    ``None``
+   ``Y``    ``X``    ``None``
+   ``X``    ``X``    ``X``
+   ``X``    ``None`` ``None``
+   ``None`` ``X``    ``None``
+   ======== ======== ==========
+
+
+*Mauris facilisis imperdiet mi, quis pellentesque urna vulputate id. Ut mi neque, condimentum a augue non, tempor mollis ipsum. Ut nec leo maximus nisi facilisis auctor. In hac habitasse platea dictumst. Nullam et posuere nulla, eget commodo ligula. Nulla eleifend euismod odio, sed vulputate ipsum ornare sit amet. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia curae; Nulla luctus, mauris pretium rhoncus ultrices, urna justo pharetra urna, sit amet porta risus diam vitae dui. Pellentesque a leo ligula. Curabitur sit amet augue id elit pretium condimentum quis a nisi. Duis egestas faucibus velit, non blandit augue finibus non. Proin vel tempor dolor, non volutpat tortor. Vestibulum sollicitudin eu elit vel placerat. Sed vestibulum purus lectus, vel feugiat est venenatis sed. In ultrices pharetra elit.*
+
+
+
+.. _CF Conventions: https://cfconventions.org/