From 54ad9bef8bb3f6460fddeaef27fe8f3852bea3c2 Mon Sep 17 00:00:00 2001 From: Elias <110238618+ESadek-MO@users.noreply.github.com> Date: Fri, 1 Dec 2023 10:09:09 +0000 Subject: [PATCH] Relocated the Technical Papers documentation to Further Topics. (#5602) * moved technical papers to further topics * updated old whatsnew * removed line 64 * created further topics index page * swapped numref for ref * fixed further topics path * unfixed further topics path * moved to bottom of userguide --- .../contributing_getting_involved.rst | 1 - docs/src/further_topics/index.rst | 20 ++++++++++++++ docs/src/further_topics/lenient_maths.rst | 4 +-- docs/src/further_topics/lenient_metadata.rst | 10 +++---- docs/src/further_topics/metadata.rst | 26 +++++++++---------- .../missing_data_handling.rst | 0 .../netcdf_io.rst | 0 docs/src/further_topics/ugrid/data_model.rst | 12 ++++----- .../um_files_loading.rst | 4 +-- docs/src/techpapers/index.rst | 14 ---------- docs/src/userguide/index.rst | 13 +--------- docs/src/whatsnew/1.7.rst | 4 +-- 12 files changed, 51 insertions(+), 57 deletions(-) create mode 100644 docs/src/further_topics/index.rst rename docs/src/{techpapers => further_topics}/missing_data_handling.rst (100%) rename docs/src/{techpapers => further_topics}/netcdf_io.rst (100%) rename docs/src/{techpapers => further_topics}/um_files_loading.rst (100%) delete mode 100644 docs/src/techpapers/index.rst diff --git a/docs/src/developers_guide/contributing_getting_involved.rst b/docs/src/developers_guide/contributing_getting_involved.rst index 9ec6559114..6ade098b6b 100644 --- a/docs/src/developers_guide/contributing_getting_involved.rst +++ b/docs/src/developers_guide/contributing_getting_involved.rst @@ -61,6 +61,5 @@ If you are new to using GitHub we recommend reading the ../generated/api/iris ../whatsnew/index - ../techpapers/index ../copyright ../voted_issues diff --git a/docs/src/further_topics/index.rst b/docs/src/further_topics/index.rst new file mode 100644 index 0000000000..016d9f80ea --- /dev/null +++ b/docs/src/further_topics/index.rst @@ -0,0 +1,20 @@ +.. _further_topics_index: + + +Further Topics +=============== + +Extra information on specific technical issues. + +.. toctree:: + :maxdepth: 1 + + filtering_warnings + metadata + lenient_metadata + lenient_maths + um_files_loading + missing_data_handling + netcdf_io + dask_best_practices/index + ugrid/index \ No newline at end of file diff --git a/docs/src/further_topics/lenient_maths.rst b/docs/src/further_topics/lenient_maths.rst index 818efe4763..51f77fb956 100644 --- a/docs/src/further_topics/lenient_maths.rst +++ b/docs/src/further_topics/lenient_maths.rst @@ -35,9 +35,9 @@ introduced and discussed the concept of lenient metadata; a more pragmatic and forgiving approach to :ref:`comparing `, :ref:`combining ` and understanding the :ref:`differences ` between your metadata -(:numref:`metadata members table`). The lenient metadata philosophy introduced +(:ref:`metadata members table`). The lenient metadata philosophy introduced there is extended to cube maths, with the view to also preserving as much common -coordinate (:numref:`metadata classes table`) information, as well as common +coordinate (:ref:`metadata classes table`) information, as well as common metadata, between the participating :class:`~iris.cube.Cube` operands as possible. Let's consolidate our understanding of lenient and strict cube maths through diff --git a/docs/src/further_topics/lenient_metadata.rst b/docs/src/further_topics/lenient_metadata.rst index b68ed501ba..5de9ad70c4 100644 --- a/docs/src/further_topics/lenient_metadata.rst +++ b/docs/src/further_topics/lenient_metadata.rst @@ -17,10 +17,10 @@ and also :ref:`conversion `. The common metadata API is implemented through the ``metadata`` property on each of the Iris `CF Conventions`_ class containers -(:numref:`metadata classes table`), and provides a common gateway for users to +(:ref:`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`) +This is primarily all thanks to the metadata classes (:ref:`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 @@ -267,7 +267,7 @@ Now, compare our metadata, >>> metadata.equal(latitude.metadata, lenient=True) True -Again, lenient equality (:numref:`lenient equality table`) offers a more +Again, lenient equality (:ref:`lenient equality table`) offers a more forgiving and practical alternative to strict behaviour. @@ -277,7 +277,7 @@ Lenient Difference ------------------ Similar to :ref:`lenient equality`, the lenient ``difference`` method -(:numref:`lenient difference table`) considers there to be no difference between +(:ref:`lenient difference table`) considers there to be no difference between comparing **something** with **nothing** (``None``). This working assumption is not naively applied to all metadata members, but rather a more pragmatic approach is adopted, as discussed later in :ref:`lenient members`. @@ -334,7 +334,7 @@ Lenient Combination ------------------- The behaviour of the lenient ``combine`` metadata class method is outlined -in :numref:`lenient combine table`, and as with :ref:`lenient equality` and +in :ref:`lenient combine table`, and as with :ref:`lenient equality` and :ref:`lenient difference` is enabled through the ``lenient`` keyword argument. The difference in behaviour between **lenient** and diff --git a/docs/src/further_topics/metadata.rst b/docs/src/further_topics/metadata.rst index 10efcdf7fe..6d32b10b7a 100644 --- a/docs/src/further_topics/metadata.rst +++ b/docs/src/further_topics/metadata.rst @@ -52,9 +52,9 @@ give them meaning. The **metadata** used to define an Iris `CF Conventions`_ class is composed of individual **metadata members**, almost all of which reference specific `CF Conventions`_ terms. The individual metadata members used to define each of -the Iris `CF Conventions`_ classes are shown in :numref:`metadata members table`. +the Iris `CF Conventions`_ classes are shown in :ref:`metadata members table`. -As :numref:`metadata members table` highlights, **specific** metadata is used to +As :ref:`metadata members table` highlights, **specific** metadata is used to define and represent each Iris `CF Conventions`_ class. This means that metadata alone, can be used to easily **identify**, **compare** and **differentiate** between individual class instances. @@ -111,7 +111,7 @@ Common Metadata API cube = iris.load_cube(iris.sample_data_path("A1B_north_america.nc")) As of Iris ``3.0.0``, a unified treatment of metadata has been applied -across each Iris class (:numref:`metadata members table`) to allow users +across each Iris class (:ref:`metadata members table`) to allow users to easily manage and manipulate their metadata in a consistent way. This is achieved through the ``metadata`` property, which allows you to @@ -158,7 +158,7 @@ Or use the ``metadata`` property again, but this time on the ``forecast_period`` CoordMetadata(standard_name='forecast_period', long_name=None, var_name='forecast_period', units=Unit('hours'), attributes={}, coord_system=None, climatological=False) Note that, the ``metadata`` property is available on each of the Iris `CF Conventions`_ -class containers referenced in :numref:`metadata members table`, and thus provides +class containers referenced in :ref:`metadata members table`, and thus provides a **common** and **consistent** approach to managing your metadata, which we'll now explore a little more fully. @@ -168,7 +168,7 @@ Metadata Classes The ``metadata`` property will return an appropriate `namedtuple`_ metadata class for each Iris `CF Conventions`_ class container. The metadata class returned by -each container class is shown in :numref:`metadata classes table` below, +each container class is shown in :ref:`metadata classes table` below, .. _metadata classes table: .. table:: - Iris namedtuple metadata classes @@ -187,7 +187,7 @@ each container class is shown in :numref:`metadata classes table` below, ========================================== ======================================================== Akin to the behaviour of a `namedtuple`_, the metadata classes in -:numref:`metadata classes table` create **tuple-like** instances i.e., they provide a +:ref:`metadata classes table` create **tuple-like** instances i.e., they provide a **snapshot** of the associated metadata member **values**, which are **not settable**, but they **may be mutable** depending on the data-type of the member. For example, given the following ``metadata`` of a :class:`~iris.coords.DimCoord`, @@ -243,13 +243,13 @@ with a **snapshot** of the container class metadata values at that point in time Skip ahead to :ref:`metadata assignment ` for a fuller discussion on options how to **set** and **get** metadata on the instance of -an Iris `CF Conventions`_ container class (:numref:`metadata classes table`). +an Iris `CF Conventions`_ container class (:ref:`metadata classes table`). Metadata Class Behaviour ------------------------ -As mentioned previously, the metadata classes in :numref:`metadata classes table` +As mentioned previously, the metadata classes in :ref:`metadata classes table` inherit the behaviour of a `namedtuple`_, and so act and feel like a `namedtuple`_, just as you might expect. For example, given the following ``metadata``, @@ -326,7 +326,7 @@ Richer Metadata Behaviour cube = iris.load_cube(iris.sample_data_path("A1B_north_america.nc")) longitude = cube.coord("longitude") -The metadata classes from :numref:`metadata classes table` support additional +The metadata classes from :ref:`metadata classes table` support additional behaviour above and beyond that of the standard Python `namedtuple`_, which allows you to easily **compare**, **combine**, **convert** and understand the **difference** between your ``metadata`` instances. @@ -340,7 +340,7 @@ Metadata Equality The metadata classes support both **equality** (``__eq__``) and **inequality** (``__ne__``), but no other `rich comparison`_ operators are implemented. This is simply because there is no obvious ordering to any collective of metadata -members, as defined in :numref:`metadata members table`. +members, as defined in :ref:`metadata members table`. For example, given the following :class:`~iris.coords.DimCoord`, @@ -455,7 +455,7 @@ be ``False``, The reason different metadata classes cannot be compared is simply because each metadata class contains **different** members, as shown in -:numref:`metadata members table`. However, there is an exception to the rule... +:ref:`metadata members table`. However, there is an exception to the rule... .. _exception rule: @@ -834,7 +834,7 @@ using ``from_metadata``, >>> print(newmeta) DimCoordMetadata(standard_name=air_temperature, var_name=air_temperature, units=K, attributes={'Conventions': 'CF-1.5', 'STASH': STASH(model=1, section=3, item=236), 'Model scenario': 'A1B', 'source': 'Data from Met Office Unified Model 6.05'}) -By examining :numref:`metadata members table`, we can see that the +By examining :ref:`metadata members table`, we can see that the :class:`~iris.cube.Cube` and :class:`~iris.coords.DimCoord` container classes share the following common metadata members, @@ -880,7 +880,7 @@ Metadata Assignment latitude = cube.coord("latitude") The ``metadata`` property available on each Iris `CF Conventions`_ container -class (:numref:`metadata classes table`) can not only be used **to get** +class (:ref:`metadata classes table`) can not only be used **to get** the metadata of an instance, but also **to set** the metadata on an instance. For example, given the following :class:`~iris.common.metadata.DimCoordMetadata` of the diff --git a/docs/src/techpapers/missing_data_handling.rst b/docs/src/further_topics/missing_data_handling.rst similarity index 100% rename from docs/src/techpapers/missing_data_handling.rst rename to docs/src/further_topics/missing_data_handling.rst diff --git a/docs/src/techpapers/netcdf_io.rst b/docs/src/further_topics/netcdf_io.rst similarity index 100% rename from docs/src/techpapers/netcdf_io.rst rename to docs/src/further_topics/netcdf_io.rst diff --git a/docs/src/further_topics/ugrid/data_model.rst b/docs/src/further_topics/ugrid/data_model.rst index 208254ada6..0b4334e0f0 100644 --- a/docs/src/further_topics/ugrid/data_model.rst +++ b/docs/src/further_topics/ugrid/data_model.rst @@ -46,7 +46,7 @@ Structured Grids (the old world) Assigning data to locations using a structured grid is essentially an act of matching coordinate arrays to each dimension of the data array. The data can also be represented as an area (instead of a point) by including a bounds array -for each coordinate array. :numref:`data_structured_grid` visualises an +for each coordinate array. :ref:`data_structured_grid` visualises an example. .. _data_structured_grid: @@ -125,7 +125,7 @@ datum per element, matched to its element by matching the datum index with the coordinate or connectivity index along the **unstructured dimension**. So for an example data array called ``foo``: ``foo[3]`` would be at position ``(x[3], y[3])`` if it were node-located, or at -``faces[3]`` if it were face-located. :numref:`data_ugrid_mesh` visualises an +``faces[3]`` if it were face-located. :ref:`data_ugrid_mesh` visualises an example of what is described above. .. _data_ugrid_mesh: @@ -152,7 +152,7 @@ example of what is described above. The mesh model also supports edges/faces/volumes having associated 'centre' coordinates - to allow point data to be assigned to these elements. 'Centre' is just a convenience term - the points can exist anywhere within their respective -elements. See :numref:`ugrid_element_centres` for a visualised example. +elements. See :ref:`ugrid_element_centres` for a visualised example. .. _ugrid_element_centres: .. figure:: images/ugrid_element_centres.svg @@ -175,7 +175,7 @@ Above we have seen how one could replicate data on a structured grid using a mesh instead. But the utility of a mesh is the extra flexibility it offers. Here are the main examples: -Every node is completely independent - every one can have unique X andY (and Z) coordinate values. See :numref:`ugrid_node_independence`. +Every node is completely independent - every one can have unique X andY (and Z) coordinate values. See :ref:`ugrid_node_independence`. .. _ugrid_node_independence: .. figure:: images/ugrid_node_independence.svg @@ -194,7 +194,7 @@ Every node is completely independent - every one can have unique X andY (and Z) Faces and volumes can have variable node counts, i.e. different numbers of sides. This is achieved by masking the unused 'slots' in the connectivity -array. See :numref:`ugrid_variable_faces`. +array. See :ref:`ugrid_variable_faces`. .. _ugrid_variable_faces: .. figure:: images/ugrid_variable_faces.svg @@ -211,7 +211,7 @@ array. See :numref:`ugrid_variable_faces`. (black circles) for faces with fewer nodes than the maximum. Data can be assigned to lines (edges) just as easily as points (nodes) or -areas (faces). See :numref:`ugrid_edge_data`. +areas (faces). See :ref:`ugrid_edge_data`. .. _ugrid_edge_data: .. figure:: images/ugrid_edge_data.svg diff --git a/docs/src/techpapers/um_files_loading.rst b/docs/src/further_topics/um_files_loading.rst similarity index 100% rename from docs/src/techpapers/um_files_loading.rst rename to docs/src/further_topics/um_files_loading.rst index f94898b3aa..9d9393f16d 100644 --- a/docs/src/techpapers/um_files_loading.rst +++ b/docs/src/further_topics/um_files_loading.rst @@ -1,5 +1,3 @@ -.. _um_files_loading: - .. testsetup:: import numpy as np @@ -13,6 +11,8 @@ np.set_printoptions(precision=8) +.. _um_files_loading: + =================================== Iris Handling of PP and Fieldsfiles =================================== diff --git a/docs/src/techpapers/index.rst b/docs/src/techpapers/index.rst deleted file mode 100644 index e97a87f39c..0000000000 --- a/docs/src/techpapers/index.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. _techpapers_index: - - -Iris Technical Papers -===================== - -Extra information on specific technical issues. - -.. toctree:: - :maxdepth: 1 - - um_files_loading.rst - missing_data_handling.rst - netcdf_io.rst diff --git a/docs/src/userguide/index.rst b/docs/src/userguide/index.rst index c87323da8e..8b7ae20cba 100644 --- a/docs/src/userguide/index.rst +++ b/docs/src/userguide/index.rst @@ -36,15 +36,4 @@ they may serve as a useful reference for future exploration. citation code_maintenance glossary - - -.. toctree:: - :maxdepth: 2 - :caption: Further Topics - - ../further_topics/filtering_warnings - ../further_topics/metadata - ../further_topics/lenient_metadata - ../further_topics/lenient_maths - ../further_topics/dask_best_practices/index - ../further_topics/ugrid/index + ../further_topics/index diff --git a/docs/src/whatsnew/1.7.rst b/docs/src/whatsnew/1.7.rst index 1d7c7c3f60..4c3f3197dc 100644 --- a/docs/src/whatsnew/1.7.rst +++ b/docs/src/whatsnew/1.7.rst @@ -329,6 +329,6 @@ Documentation * A clarification of the behaviour of :func:`iris.analysis.calculus.differentiate`. -* A new :doc:`"Technical Papers" ` section has been added to +* A new Technical Papers section has been added to the documentation along with the addition of a paper providing an - :doc:`overview of the load process for UM-like fileformats (e.g. PP and Fieldsfile) `. + :ref:`overview of the load process for UM-like fileformats (e.g. PP and Fieldsfile) `.