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

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

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

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 <lenient equality>`,
 :ref:`combining <lenient combination>` and understanding the
 :ref:`differences <lenient difference>` 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

docs/src/further_topics/lenient_metadata.rst

@@ -17,10 +17,10 @@ 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
-(: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

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 <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

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

docs/src/techpapers/um_files_loading.rst → 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
 ===================================

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

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" </techpapers/index>` 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) </techpapers/um_files_loading>`.
+  :ref:`overview of the load process for UM-like fileformats (e.g. PP and Fieldsfile) <um_files_loading>`.