Built using Python {{ python_version }}.
diff --git a/docs/src/_templates/custom_sidebar_logo_version.html b/docs/src/_templates/custom_sidebar_logo_version.html new file mode 100644 index 0000000000..48bbe604a0 --- /dev/null +++ b/docs/src/_templates/custom_sidebar_logo_version.html @@ -0,0 +1,20 @@ +{% if on_rtd %} + {% if rtd_version == 'latest' %} + +
+
+ {% elif rtd_version == 'stable' %}
+
+ 
+
+ {% else %}
+
+ 
+
+ {% endif %}
+{%- else %}
+ {# not on rtd #}
+
+ 
+
+{%- endif %}
diff --git a/docs/src/_templates/footer.html b/docs/src/_templates/footer.html
deleted file mode 100644
index 1d5fb08b78..0000000000
--- a/docs/src/_templates/footer.html
+++ /dev/null
@@ -1,5 +0,0 @@
-{% extends "!footer.html" %}
-{% block extrafooter %}
- Built using Python {{ python_version }}.
- {{ super() }}
-{% endblock %}
diff --git a/docs/src/_templates/layout.html b/docs/src/_templates/layout.html
index 96a2e0913e..7377e866b7 100644
--- a/docs/src/_templates/layout.html
+++ b/docs/src/_templates/layout.html
@@ -1,16 +1,16 @@
-{% extends "!layout.html" %}
+{% extends "pydata_sphinx_theme/layout.html" %}
-{# This uses blocks. See:
+{# This uses blocks. See:
https://www.sphinx-doc.org/en/master/templating.html
#}
-/*---------------------------------------------------------------------------*/
-{%- block document %}
- {% if READTHEDOCS and rtd_version == 'latest' %}
-
+ {%- block docs_body %}
+
+ {% if on_rtd and rtd_version == 'latest' %}
+
@@ -19,29 +19,3 @@
{{ super() }}
{%- endblock %}
-
-/*-----------------------------------------------------z----------------------*/
-
-{% block menu %}
- {{ super() }}
-
- {# menu_links and menu_links_name are set in conf.py (html_context) #}
-
- {% if menu_links %}
- `
-
- where you should replace `` with the major and minor version
- of Iris in which this API is first deprecated. For example: `1.8`.
-
- As with the deprecation warning, you should include advice on how to
- avoid using the deprecated API within the content of this directive.
- Feel free to include more detail in the updated docstring than in the
- deprecation warning.
- - You should check the documentation for references to the deprecated
- API and update them as appropriate.
+- Using the deprecated API must result in a concise deprecation warning which
+ is an instance of :class:`iris.IrisDeprecation`.
+ It is easiest to call
+ :func:`iris._deprecation.warn_deprecated`, which is a
+ simple wrapper to :func:`warnings.warn` with the signature
+ `warn_deprecation(message, **kwargs)`.
+- Where possible, your deprecation warning should include advice on
+ how to avoid using the deprecated API. For example, you might
+ reference a preferred API, or more detailed documentation elsewhere.
+- You must update the docstring for the deprecated API to include a
+ Sphinx deprecation directive:
+
+ :literal:`.. deprecated:: `
+
+ where you should replace `` with the major and minor version
+ of Iris in which this API is first deprecated. For example: `1.8`.
+
+ As with the deprecation warning, you should include advice on how to
+ avoid using the deprecated API within the content of this directive.
+ Feel free to include more detail in the updated docstring than in the
+ deprecation warning.
+- You should check the documentation for references to the deprecated
+ API and update them as appropriate.
Changing a Default
------------------
@@ -64,14 +64,14 @@ it causes the corresponding public API to use its new default behaviour.
The following points apply in addition to those for removing a public
API:
- - You should add a new boolean attribute to :data:`iris.FUTURE` (by
- modifying :class:`iris.Future`) that controls the default behaviour
- of the public API that needs updating. The initial state of the new
- boolean attribute should be `False`. You should name the new boolean
- attribute to indicate that setting it to `True` will select the new
- default behaviour.
- - You should include a reference to this :data:`iris.FUTURE` flag in your
- deprecation warning and corresponding Sphinx deprecation directive.
+- You should add a new boolean attribute to :data:`iris.FUTURE` (by
+ modifying :class:`iris.Future`) that controls the default behaviour
+ of the public API that needs updating. The initial state of the new
+ boolean attribute should be `False`. You should name the new boolean
+ attribute to indicate that setting it to `True` will select the new
+ default behaviour.
+- You should include a reference to this :data:`iris.FUTURE` flag in your
+ deprecation warning and corresponding Sphinx deprecation directive.
Removing a Deprecation
@@ -94,11 +94,11 @@ and/or example code should be removed/updated as appropriate.
Changing a Default
------------------
- - You should update the initial state of the relevant boolean attribute
- of :data:`iris.FUTURE` to `True`.
- - You should deprecate setting the relevant boolean attribute of
- :class:`iris.Future` in the same way as described in
- :ref:`removing-a-public-api`.
+- You should update the initial state of the relevant boolean attribute
+ of :data:`iris.FUTURE` to `True`.
+- You should deprecate setting the relevant boolean attribute of
+ :class:`iris.Future` in the same way as described in
+ :ref:`removing-a-public-api`.
.. rubric:: Footnotes
diff --git a/docs/src/developers_guide/contributing_getting_involved.rst b/docs/src/developers_guide/contributing_getting_involved.rst
index f7bd4733a3..f4e677cea2 100644
--- a/docs/src/developers_guide/contributing_getting_involved.rst
+++ b/docs/src/developers_guide/contributing_getting_involved.rst
@@ -1,8 +1,9 @@
.. include:: ../common_links.inc
.. _development_where_to_start:
+.. _developers_guide:
-Getting Involved
+Developers Guide
----------------
Iris_ is an Open Source project hosted on Github and as such anyone with a
@@ -17,7 +18,7 @@ The `Iris GitHub`_ project has been configured to use templates for each of
the above issue types when creating a `new issue`_ to ensure the appropriate
information is provided.
-Alternatively, **join the conversation** in `Iris GitHub Discussions`_, when
+Alternatively, **join the conversation** in Iris `GitHub Discussions`_, when
you would like the opinions of the Iris community.
A `pull request`_ may also be created by anyone who has become a
@@ -25,7 +26,7 @@ A `pull request`_ may also be created by anyone who has become a
``main`` branch are only given to **core developers** of Iris_, this is
to ensure a measure of control.
-To get started we suggest reading recent `issues`_, `discussions`_ and
+To get started we suggest reading recent `issues`_, `GitHub Discussions`_ and
`pull requests`_ for Iris.
If you are new to using GitHub we recommend reading the
@@ -36,5 +37,29 @@ If you are new to using GitHub we recommend reading the
`Governance `_
section of the `SciTools`_ ogranization web site.
-
.. _GitHub getting started: https://docs.github.com/en/github/getting-started-with-github
+
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Developers Guide
+ :name: development_index
+ :hidden:
+
+ gitwash/index
+ contributing_documentation
+ contributing_codebase_index
+ contributing_changes
+ release
+
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Reference
+ :hidden:
+
+ ../generated/api/iris
+ ../whatsnew/index
+ ../techpapers/index
+ ../copyright
+ ../voted_issues
diff --git a/docs/src/developers_guide/contributing_graphics_tests.rst b/docs/src/developers_guide/contributing_graphics_tests.rst
index 1268aa2686..07e2301141 100644
--- a/docs/src/developers_guide/contributing_graphics_tests.rst
+++ b/docs/src/developers_guide/contributing_graphics_tests.rst
@@ -44,24 +44,24 @@ reference images in the Iris repository itself.
This consists of:
- * The ``iris.tests.IrisTest_nometa.check_graphic`` function uses a perceptual
- **image hash** of the outputs (see https://github.com/JohannesBuchner/imagehash)
- as the basis for checking test results.
+* The ``iris.tests.IrisTest_nometa.check_graphic`` function uses a perceptual
+ **image hash** of the outputs (see https://github.com/JohannesBuchner/imagehash)
+ as the basis for checking test results.
- * The hashes of known **acceptable** results for each test are stored in a
- lookup dictionary, saved to the repo file
- ``lib/iris/tests/results/imagerepo.json``
- (`link `_) .
+* The hashes of known **acceptable** results for each test are stored in a
+ lookup dictionary, saved to the repo file
+ ``lib/iris/tests/results/imagerepo.json``
+ (`link `_) .
- * An actual reference image for each hash value is stored in a *separate*
- public repository https://github.com/SciTools/test-iris-imagehash.
+* An actual reference image for each hash value is stored in a *separate*
+ public repository https://github.com/SciTools/test-iris-imagehash.
- * The reference images allow human-eye assessment of whether a new output is
- judged to be close enough to the older ones, or not.
+* The reference images allow human-eye assessment of whether a new output is
+ judged to be close enough to the older ones, or not.
- * The utility script ``iris/tests/idiff.py`` automates checking, enabling the
- developer to easily compare proposed new **acceptable** result images
- against the existing accepted reference images, for each failing test.
+* The utility script ``iris/tests/idiff.py`` automates checking, enabling the
+ developer to easily compare proposed new **acceptable** result images
+ against the existing accepted reference images, for each failing test.
The acceptable images for each test can be viewed online. The :ref:`testing.imagehash_index` lists all the graphical tests in the test suite and
shows the known acceptable result images for comparison.
@@ -92,29 +92,29 @@ you should follow:
If the change is **accepted**:
- * the imagehash value of the new result image is added into the relevant
- set of 'valid result hashes' in the image result database file,
- ``tests/results/imagerepo.json``
+ * the imagehash value of the new result image is added into the relevant
+ set of 'valid result hashes' in the image result database file,
+ ``tests/results/imagerepo.json``
- * the relevant output file in ``tests/result_image_comparison`` is
- renamed according to the image hash value, as ``.png``.
- A copy of this new PNG file must then be added into the reference image
- repository at https://github.com/SciTools/test-iris-imagehash
- (See below).
+ * the relevant output file in ``tests/result_image_comparison`` is
+ renamed according to the image hash value, as ``.png``.
+ A copy of this new PNG file must then be added into the reference image
+ repository at https://github.com/SciTools/test-iris-imagehash
+ (See below).
If a change is **skipped**:
- * no further changes are made in the repo.
+ * no further changes are made in the repo.
- * when you run ``iris/tests/idiff.py`` again, the skipped choice will be
- presented again.
+ * when you run ``iris/tests/idiff.py`` again, the skipped choice will be
+ presented again.
If a change is **rejected**:
- * the output image is deleted from ``result_image_comparison``.
+ * the output image is deleted from ``result_image_comparison``.
- * when you run ``iris/tests/idiff.py`` again, the skipped choice will not
- appear, unless the relevant failing test is re-run.
+ * when you run ``iris/tests/idiff.py`` again, the skipped choice will not
+ appear, unless the relevant failing test is re-run.
#. **Now re-run the tests**. The **new** result should now be recognised and the
relevant test should pass. However, some tests can perform *multiple*
@@ -132,16 +132,16 @@ To add your changes to Iris, you need to make two pull requests (PR).
#. The first PR is made in the ``test-iris-imagehash`` repository, at
https://github.com/SciTools/test-iris-imagehash.
- * First, add all the newly-generated referenced PNG files into the
- ``images/v4`` directory. In your Iris repo, these files are to be found
- in the temporary results folder ``iris/tests/result_image_comparison``.
+ * First, add all the newly-generated referenced PNG files into the
+ ``images/v4`` directory. In your Iris repo, these files are to be found
+ in the temporary results folder ``iris/tests/result_image_comparison``.
- * Then, to update the file which lists available images,
- ``v4_files_listing.txt``, run from the project root directory::
+ * Then, to update the file which lists available images,
+ ``v4_files_listing.txt``, run from the project root directory::
- python recreate_v4_files_listing.py
+ python recreate_v4_files_listing.py
- * Create a PR proposing these changes, in the usual way.
+ * Create a PR proposing these changes, in the usual way.
#. The second PR is created in the Iris_ repository, and
should only include the change to the image results database,
diff --git a/docs/src/developers_guide/contributing_pull_request_checklist.rst b/docs/src/developers_guide/contributing_pull_request_checklist.rst
index 5afb461d68..524b5d2c17 100644
--- a/docs/src/developers_guide/contributing_pull_request_checklist.rst
+++ b/docs/src/developers_guide/contributing_pull_request_checklist.rst
@@ -16,8 +16,8 @@ is merged. Before submitting a pull request please consider this list.
#. **Provide a helpful description** of the Pull Request. This should include:
- * The aim of the change / the problem addressed / a link to the issue.
- * How the change has been delivered.
+ * The aim of the change / the problem addressed / a link to the issue.
+ * How the change has been delivered.
#. **Include a "What's New" entry**, if appropriate.
See :ref:`whats_new_contributions`.
@@ -51,12 +51,12 @@ is merged. Before submitting a pull request please consider this list.
#. **Check for updates needed for supporting projects for test or example
data**. For example:
- * `iris-test-data`_ is a github project containing all the data to support
- the tests.
- * `iris-sample-data`_ is a github project containing all the data to support
- the gallery and examples.
- * `test-iris-imagehash`_ is a github project containing reference plot
- images to support Iris :ref:`testing.graphics`.
+ * `iris-test-data`_ is a github project containing all the data to support
+ the tests.
+ * `iris-sample-data`_ is a github project containing all the data to support
+ the gallery and examples.
+ * `test-iris-imagehash`_ is a github project containing reference plot
+ images to support Iris :ref:`testing.graphics`.
If new files are required by tests or code examples, they must be added to
the appropriate supporting project via a suitable pull-request. This pull
diff --git a/docs/src/developers_guide/contributing_testing.rst b/docs/src/developers_guide/contributing_testing.rst
index d0c96834a9..a65bcebd55 100644
--- a/docs/src/developers_guide/contributing_testing.rst
+++ b/docs/src/developers_guide/contributing_testing.rst
@@ -8,8 +8,8 @@ Test Categories
There are two main categories of tests within Iris:
- - :ref:`testing.unit_test`
- - :ref:`testing.integration`
+- :ref:`testing.unit_test`
+- :ref:`testing.integration`
Ideally, all code changes should be accompanied by one or more unit
tests, and by zero or more integration tests.
diff --git a/docs/src/developers_guide/documenting/docstrings.rst b/docs/src/developers_guide/documenting/docstrings.rst
index 8a06024ee2..ef0679aac0 100644
--- a/docs/src/developers_guide/documenting/docstrings.rst
+++ b/docs/src/developers_guide/documenting/docstrings.rst
@@ -10,8 +10,8 @@ the code and may be read directly in the source or via the :ref:`Iris`.
This document has been influenced by the following PEP's,
- * Attribute Docstrings :pep:`224`
- * Docstring Conventions :pep:`257`
+* Attribute Docstrings :pep:`224`
+* Docstring Conventions :pep:`257`
For consistency always use:
diff --git a/docs/src/developers_guide/documenting/rest_guide.rst b/docs/src/developers_guide/documenting/rest_guide.rst
index 4845132b15..c4330b1e63 100644
--- a/docs/src/developers_guide/documenting/rest_guide.rst
+++ b/docs/src/developers_guide/documenting/rest_guide.rst
@@ -14,8 +14,8 @@ reST is a lightweight markup language intended to be highly readable in
source format. This guide will cover some of the more frequently used advanced
reST markup syntaxes, for the basics of reST the following links may be useful:
- * https://www.sphinx-doc.org/en/master/usage/restructuredtext/
- * http://packages.python.org/an_example_pypi_project/sphinx.html
+* https://www.sphinx-doc.org/en/master/usage/restructuredtext/
+* http://packages.python.org/an_example_pypi_project/sphinx.html
Reference documentation for reST can be found at http://docutils.sourceforge.net/rst.html.
diff --git a/docs/src/developers_guide/documenting/whats_new_contributions.rst b/docs/src/developers_guide/documenting/whats_new_contributions.rst
index 576fc5f6a6..c9dbe04b71 100644
--- a/docs/src/developers_guide/documenting/whats_new_contributions.rst
+++ b/docs/src/developers_guide/documenting/whats_new_contributions.rst
@@ -4,21 +4,16 @@
Contributing a "What's New" Entry
=================================
-Iris uses a file named ``dev.rst`` to keep a draft of upcoming development changes
-that will form the next stable release. Contributions to the :ref:`iris_whatsnew`
-document are written by the developer most familiar with the change made.
-The contribution should be included as part of the Iris Pull Request that
-introduces the change.
+Iris uses a file named ``latest.rst`` to keep a draft of upcoming development
+changes that will form the next stable release. Contributions to the
+:ref:`iris_whatsnew` document are written by the developer most familiar
+with the change made. The contribution should be included as part of
+the Iris Pull Request that introduces the change.
-The ``dev.rst`` and the past release notes are kept in the
+The ``latest.rst`` and the past release notes are kept in the
``docs/src/whatsnew/`` directory. If you are writing the first contribution after
-an Iris release: **create the new** ``dev.rst`` by copying the content from
-``dev.rst.template`` in the same directory.
-
-.. note::
-
- Ensure that the symbolic link ``latest.rst`` references the ``dev.rst`` file
- within the ``docs/src/whatsnew`` directory.
+an Iris release: **create the new** ``latest.rst`` by copying the content from
+``latest.rst.template`` in the same directory.
Since the `Contribution categories`_ include Internal changes, **all** Iris
Pull Requests should be accompanied by a "What's New" contribution.
@@ -27,7 +22,7 @@ Pull Requests should be accompanied by a "What's New" contribution.
Git Conflicts
=============
-If changes to ``dev.rst`` are being suggested in several simultaneous
+If changes to ``latest.rst`` are being suggested in several simultaneous
Iris Pull Requests, Git will likely encounter merge conflicts. If this
situation is thought likely (large PR, high repo activity etc.):
@@ -38,7 +33,7 @@ situation is thought likely (large PR, high repo activity etc.):
a **new pull request** be created specifically for the "What's New" entry,
which references the main pull request and titled (e.g. for PR#9999):
- What's New for #9999
+ What's New for #9999
* PR author: create the "What's New" pull request
@@ -48,7 +43,7 @@ situation is thought likely (large PR, high repo activity etc.):
* PR reviewer: review the "What's New" PR, merge once acceptable
-These measures should mean the suggested ``dev.rst`` changes are outstanding
+These measures should mean the suggested ``latest.rst`` changes are outstanding
for the minimum time, minimising conflicts and minimising the need to rebase or
merge from trunk.
diff --git a/docs/src/developers_guide/gitwash/development_workflow.rst b/docs/src/developers_guide/gitwash/development_workflow.rst
index 0536ebfb62..6e74e8546d 100644
--- a/docs/src/developers_guide/gitwash/development_workflow.rst
+++ b/docs/src/developers_guide/gitwash/development_workflow.rst
@@ -25,7 +25,7 @@ In what follows we'll refer to the upstream iris ``main`` branch, as
* If you can possibly avoid it, avoid merging trunk or any other branches into
your feature branch while you are working.
* If you do find yourself merging from trunk, consider :ref:`rebase-on-trunk`
-* Ask on the `Iris GitHub Discussions`_ if you get stuck.
+* Ask on the Iris `GitHub Discussions`_ if you get stuck.
* Ask for code review!
This way of working helps to keep work well organized, with readable history.
diff --git a/docs/src/developers_guide/release.rst b/docs/src/developers_guide/release.rst
index f4d44781fc..a918253ef7 100644
--- a/docs/src/developers_guide/release.rst
+++ b/docs/src/developers_guide/release.rst
@@ -19,7 +19,8 @@ A Release Manager will be nominated for each release of Iris. This role involves
* deciding which features and bug fixes should be included in the release
* managing the project board for the release
-* using a `GitHub Releases Discussion Forum`_ for documenting intent and capturing any
+* using :discussion:`GitHub Discussion releases category `
+ for documenting intent and capturing any
discussion about the release
The Release Manager will make the release, ensuring that all the steps outlined
@@ -183,7 +184,7 @@ back onto the ``SciTools/iris`` ``main`` branch.
To achieve this, first cut a local branch from the latest ``main`` branch,
and `git merge` the :literal:`.x` release branch into it. Ensure that the
-``iris.__version__``, ``docs/src/whatsnew/index.rst``, ``docs/src/whatsnew/dev.rst``,
+``iris.__version__``, ``docs/src/whatsnew/index.rst``,
and ``docs/src/whatsnew/latest.rst`` are correct, before committing these changes
and then proposing a pull-request on the ``main`` branch of ``SciTools/iris``.
@@ -218,24 +219,22 @@ Release Steps
#. Update the ``iris.__init__.py`` version string e.g., to ``1.9.0``
#. Update the ``whatsnew`` for the release:
- * Use ``git`` to rename ``docs/src/whatsnew/dev.rst`` to the release
- version file ``v1.9.rst``
- * Update the symbolic link ``latest.rst`` to reference the latest
- whatsnew ``v1.9.rst``
- * Use ``git`` to delete the ``docs/src/whatsnew/dev.rst.template`` file
- * In ``v1.9.rst`` remove the ``[unreleased]`` caption from the page title.
- Note that, the Iris version and release date are updated automatically
- when the documentation is built
- * Review the file for correctness
- * Work with the development team to populate the ``Release Highlights``
- dropdown at the top of the file, which provides extra detail on notable
- changes
- * Use ``git`` to add and commit all changes, including removal of
- ``dev.rst.template`` and update to the ``latest.rst`` symbolic link.
+ * Use ``git`` to rename ``docs/src/whatsnew/latest.rst`` to the release
+ version file ``v1.9.rst``
+ * Use ``git`` to delete the ``docs/src/whatsnew/latest.rst.template`` file
+ * In ``v1.9.rst`` remove the ``[unreleased]`` caption from the page title.
+ Note that, the Iris version and release date are updated automatically
+ when the documentation is built
+ * Review the file for correctness
+ * Work with the development team to populate the ``Release Highlights``
+ dropdown at the top of the file, which provides extra detail on notable
+ changes
+ * Use ``git`` to add and commit all changes, including removal of
+ ``latest.rst.template``.
#. Update the ``whatsnew`` index ``docs/src/whatsnew/index.rst``
- * Remove the reference to ``dev.rst``
+ * Remove the reference to ``latest.rst``
* Add a reference to ``v1.9.rst`` to the top of the list
#. Check your changes by building the documentation and reviewing
@@ -261,7 +260,6 @@ Post Release Steps
.. _SciTools/iris: https://github.com/SciTools/iris
.. _tag on the SciTools/Iris: https://github.com/SciTools/iris/releases
-.. _GitHub Releases Discussion Forum: https://github.com/SciTools/iris/discussions/categories/releases
.. _conda-forge Anaconda channel: https://anaconda.org/conda-forge/iris
.. _conda-forge iris-feedstock: https://github.com/conda-forge/iris-feedstock
.. _CFEP-05: https://github.com/conda-forge/cfep/blob/master/cfep-05.md
diff --git a/docs/src/further_topics/index.rst b/docs/src/further_topics/index.rst
deleted file mode 100644
index 81bff2f764..0000000000
--- a/docs/src/further_topics/index.rst
+++ /dev/null
@@ -1,26 +0,0 @@
-.. _further topics:
-
-Introduction
-============
-
-Some specific areas of Iris may require further explanation or a deep dive
-into additional detail above and beyond that offered by the
-:ref:`User Guide `.
-
-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 :issue:`GitHub Documentation Issue`
- on `SciTools/Iris`_.
-
-
-* :doc:`metadata`
-* :doc:`lenient_metadata`
-* :doc:`lenient_maths`
-* :ref:`ugrid`
-
-
-.. _SciTools/iris: https://github.com/SciTools/iris
diff --git a/docs/src/further_topics/metadata.rst b/docs/src/further_topics/metadata.rst
index 1b81f7055c..de1afb15af 100644
--- a/docs/src/further_topics/metadata.rst
+++ b/docs/src/further_topics/metadata.rst
@@ -1,3 +1,4 @@
+.. _further topics:
.. _metadata:
Metadata
@@ -63,25 +64,26 @@ For example, the collective metadata used to define an
``var_name``, ``units``, and ``attributes`` members. Note that, these are the
actual `data attribute`_ names of the metadata members on the Iris class.
+
.. _metadata members table:
-.. table:: - Iris classes that model `CF Conventions`_ metadata
+.. table:: Iris classes that model `CF Conventions`_ metadata
:widths: auto
:align: center
- =================== ======================================= ============================== ========================================== ================================= ======================== ============================== ===================
- Metadata Members :class:`~iris.coords.AncillaryVariable` :class:`~iris.coords.AuxCoord` :class:`~iris.aux_factory.AuxCoordFactory` :class:`~iris.coords.CellMeasure` :class:`~iris.cube.Cube` :class:`~iris.coords.DimCoord` Metadata Members
- =================== ======================================= ============================== ========================================== ================================= ======================== ============================== ===================
- ``standard_name`` ✔ ✔ ✔ ✔ ✔ ✔ ``standard_name``
- ``long_name`` ✔ ✔ ✔ ✔ ✔ ✔ ``long_name``
- ``var_name`` ✔ ✔ ✔ ✔ ✔ ✔ ``var_name``
- ``units`` ✔ ✔ ✔ ✔ ✔ ✔ ``units``
- ``attributes`` ✔ ✔ ✔ ✔ ✔ ✔ ``attributes``
- ``coord_system`` ✔ ✔ ✔ ``coord_system``
- ``climatological`` ✔ ✔ ✔ ``climatological``
- ``measure`` ✔ ``measure``
- ``cell_methods`` ✔ ``cell_methods``
- ``circular`` ✔ ``circular``
- =================== ======================================= ============================== ========================================== ================================= ======================== ============================== ===================
+ =================== ======================================= ============================== ========================================== ================================= ======================== ==============================
+ Metadata Members :class:`~iris.coords.AncillaryVariable` :class:`~iris.coords.AuxCoord` :class:`~iris.aux_factory.AuxCoordFactory` :class:`~iris.coords.CellMeasure` :class:`~iris.cube.Cube` :class:`~iris.coords.DimCoord`
+ =================== ======================================= ============================== ========================================== ================================= ======================== ==============================
+ ``standard_name`` ✔ ✔ ✔ ✔ ✔ ✔
+ ``long_name`` ✔ ✔ ✔ ✔ ✔ ✔
+ ``var_name`` ✔ ✔ ✔ ✔ ✔ ✔
+ ``units`` ✔ ✔ ✔ ✔ ✔ ✔
+ ``attributes`` ✔ ✔ ✔ ✔ ✔ ✔
+ ``coord_system`` ✔ ✔ ✔
+ ``climatological`` ✔ ✔ ✔
+ ``measure`` ✔
+ ``cell_methods`` ✔
+ ``circular`` ✔
+ =================== ======================================= ============================== ========================================== ================================= ======================== ==============================
.. note::
diff --git a/docs/src/further_topics/ugrid/data_model.rst b/docs/src/further_topics/ugrid/data_model.rst
index 4a2f64f627..55e4f79a96 100644
--- a/docs/src/further_topics/ugrid/data_model.rst
+++ b/docs/src/further_topics/ugrid/data_model.rst
@@ -52,7 +52,7 @@ example.
.. _data_structured_grid:
.. figure:: images/data_structured_grid.svg
:alt: Diagram of how data is represented on a structured grid
- :align: right
+ :align: left
:width: 1280
Data on a structured grid.
@@ -131,7 +131,7 @@ example of what is described above.
.. _data_ugrid_mesh:
.. figure:: images/data_ugrid_mesh.svg
:alt: Diagram of how data is represented on an unstructured mesh
- :align: right
+ :align: left
:width: 1280
Data on an unstructured mesh
@@ -157,7 +157,7 @@ elements. See :numref:`ugrid_element_centres` for a visualised example.
.. _ugrid_element_centres:
.. figure:: images/ugrid_element_centres.svg
:alt: Diagram demonstrating mesh face-centred data.
- :align: right
+ :align: left
:width: 1280
Data can be assigned to mesh edge/face/volume 'centres'
@@ -180,7 +180,7 @@ Every node is completely independent - every one can have unique X andY (and Z)
.. _ugrid_node_independence:
.. figure:: images/ugrid_node_independence.svg
:alt: Diagram demonstrating the independence of each mesh node
- :align: right
+ :align: left
:width: 300
Every mesh node is completely independent
@@ -199,7 +199,7 @@ array. See :numref:`ugrid_variable_faces`.
.. _ugrid_variable_faces:
.. figure:: images/ugrid_variable_faces.svg
:alt: Diagram demonstrating mesh faces with variable node counts
- :align: right
+ :align: left
:width: 300
Mesh faces can have different node counts (using masking)
@@ -216,7 +216,7 @@ areas (faces). See :numref:`ugrid_edge_data`.
.. _ugrid_edge_data:
.. figure:: images/ugrid_edge_data.svg
:alt: Diagram demonstrating data assigned to mesh edges
- :align: right
+ :align: left
:width: 300
Data can be assigned to mesh edges
diff --git a/docs/src/getting_started.rst b/docs/src/getting_started.rst
new file mode 100644
index 0000000000..24299a4060
--- /dev/null
+++ b/docs/src/getting_started.rst
@@ -0,0 +1,15 @@
+.. _getting_started_index:
+
+Getting Started
+===============
+
+To get started with Iris we recommend reading :ref:`why_iris` was created and to
+explore the examples in the :ref:`gallery_index` after :ref:`installing_iris`
+Iris.
+
+.. toctree::
+ :maxdepth: 1
+
+ why_iris
+ installing
+ generated/gallery/index
\ No newline at end of file
diff --git a/docs/src/index.rst b/docs/src/index.rst
index d247b93411..fb0e93b1ae 100644
--- a/docs/src/index.rst
+++ b/docs/src/index.rst
@@ -1,7 +1,9 @@
+.. include:: common_links.inc
.. _iris_docs:
-Iris |version|
-========================
+
+Iris
+====
**A powerful, format-agnostic, community-driven Python package for analysing
and visualising Earth science data.**
@@ -11,158 +13,137 @@ giving you a powerful, format-agnostic interface for working with your data.
It excels when working with multi-dimensional Earth Science data, where tabular
representations become unwieldy and inefficient.
-`CF Standard names `_,
-`units `_, and coordinate metadata
-are built into Iris, giving you a rich and expressive interface for maintaining
-an accurate representation of your data. Its treatment of data and
-associated metadata as first-class objects includes:
-
-* visualisation interface based on `matplotlib `_ from
+`Flaticon `_
+that may be useful but we do not actively monitor this.
+
+The legacy support resources:
- installing
- generated/gallery/index
+* `Users Google Group `_
+* `Developers Google Group `_
+* `Legacy Documentation`_ (Iris 2.4 or earlier)
.. toctree::
+ :caption: Getting Started
:maxdepth: 1
- :caption: What's New in Iris
:hidden:
- whatsnew/latest
- Archive
+ getting_started
.. toctree::
- :maxdepth: 1
:caption: User Guide
+ :maxdepth: 1
:name: userguide_index
:hidden:
userguide/index
- userguide/iris_cubes
- userguide/loading_iris_cubes
- userguide/saving_iris_cubes
- userguide/navigating_a_cube
- userguide/subsetting_a_cube
- userguide/real_and_lazy_data
- userguide/plotting_a_cube
- userguide/interpolation_and_regridding
- userguide/merge_and_concat
- userguide/cube_statistics
- userguide/cube_maths
- userguide/citation
- userguide/code_maintenance
-
-
-.. _developers_guide:
+
.. toctree::
+ :caption: Developers Guide
:maxdepth: 1
- :caption: Further Topics
+ :name: developers_index
:hidden:
- further_topics/index
- further_topics/metadata
- further_topics/lenient_metadata
- further_topics/lenient_maths
- further_topics/ugrid/index
+ developers_guide/contributing_getting_involved
.. toctree::
- :maxdepth: 2
- :caption: Developers Guide
- :name: development_index
+ :caption: Iris API
+ :maxdepth: 1
:hidden:
- developers_guide/contributing_getting_involved
- developers_guide/gitwash/index
- developers_guide/contributing_documentation
- developers_guide/contributing_codebase_index
- developers_guide/contributing_changes
- developers_guide/release
+ generated/api/iris
.. toctree::
+ :caption: Developers Guide
:maxdepth: 1
- :caption: Reference
+ :name: whats_new_index
:hidden:
- generated/api/iris
- techpapers/index
- copyright
- voted_issues
+ whatsnew/index
+
+.. todolist::
\ No newline at end of file
diff --git a/docs/src/installing.rst b/docs/src/installing.rst
index 37a8942ab3..33b15610fa 100644
--- a/docs/src/installing.rst
+++ b/docs/src/installing.rst
@@ -1,7 +1,7 @@
.. _installing_iris:
-Installing Iris
-===============
+Installing
+==========
Iris is available using conda for the following platforms:
diff --git a/docs/src/userguide/code_maintenance.rst b/docs/src/userguide/code_maintenance.rst
index b2b498bc80..c01c1975a7 100644
--- a/docs/src/userguide/code_maintenance.rst
+++ b/docs/src/userguide/code_maintenance.rst
@@ -12,17 +12,17 @@ In practice, as Iris develops, most users will want to periodically upgrade
their installed version to access new features or at least bug fixes.
This is obvious if you are still developing other code that uses Iris, or using
-code from other sources.
+code from other sources.
However, even if you have only legacy code that remains untouched, some code
maintenance effort is probably still necessary:
- * On the one hand, *in principle*, working code will go on working, as long
- as you don't change anything else.
+* On the one hand, *in principle*, working code will go on working, as long
+ as you don't change anything else.
- * However, such "version stasis" can easily become a growing burden, if you
- are simply waiting until an update becomes unavoidable, often that will
- eventually occur when you need to update some other software component,
- for some completely unconnected reason.
+* However, such "version stasis" can easily become a growing burden, if you
+ are simply waiting until an update becomes unavoidable, often that will
+ eventually occur when you need to update some other software component,
+ for some completely unconnected reason.
Principles of Change Management
@@ -35,13 +35,13 @@ In Iris, however, we aim to reduce code maintenance problems to an absolute
minimum by following defined change management rules.
These ensure that, *within a major release number* :
- * you can be confident that your code will still work with subsequent minor
- releases
+* you can be confident that your code will still work with subsequent minor
+ releases
- * you will be aware of future incompatibility problems in advance
+* you will be aware of future incompatibility problems in advance
- * you can defer making code compatibility changes for some time, until it
- suits you
+* you can defer making code compatibility changes for some time, until it
+ suits you
The above applies to minor version upgrades : e.g. code that works with version
"1.4.2" should still work with a subsequent minor release such as "1.5.0" or
diff --git a/docs/src/userguide/index.rst b/docs/src/userguide/index.rst
index 2a3b32fe11..08923e7662 100644
--- a/docs/src/userguide/index.rst
+++ b/docs/src/userguide/index.rst
@@ -1,31 +1,47 @@
.. _user_guide_index:
.. _user_guide_introduction:
-Introduction
-============
+User Guide
+==========
-If you are reading this user guide for the first time it is strongly recommended that you read the user guide
-fully before experimenting with your own data files.
+If you are reading this user guide for the first time it is strongly
+recommended that you read the user guide fully before experimenting with your
+own data files.
-
-Much of the content has supplementary links to the reference documentation; you will not need to follow these
-links in order to understand the guide but they may serve as a useful reference for future exploration.
+Much of the content has supplementary links to the reference documentation;
+you will not need to follow these links in order to understand the guide but
+they may serve as a useful reference for future exploration.
.. only:: html
- Since later pages depend on earlier ones, try reading this user guide sequentially using the ``next`` and ``previous`` links.
-
-
-* :doc:`iris_cubes`
-* :doc:`loading_iris_cubes`
-* :doc:`saving_iris_cubes`
-* :doc:`navigating_a_cube`
-* :doc:`subsetting_a_cube`
-* :doc:`real_and_lazy_data`
-* :doc:`plotting_a_cube`
-* :doc:`interpolation_and_regridding`
-* :doc:`merge_and_concat`
-* :doc:`cube_statistics`
-* :doc:`cube_maths`
-* :doc:`citation`
-* :doc:`code_maintenance`
+ Since later pages depend on earlier ones, try reading this user guide
+ sequentially using the ``next`` and ``previous`` links at the bottom
+ of each page.
+
+
+.. toctree::
+ :maxdepth: 2
+
+ iris_cubes
+ loading_iris_cubes
+ saving_iris_cubes
+ navigating_a_cube
+ subsetting_a_cube
+ real_and_lazy_data
+ plotting_a_cube
+ interpolation_and_regridding
+ merge_and_concat
+ cube_statistics
+ cube_maths
+ citation
+ code_maintenance
+
+
+.. toctree::
+ :maxdepth: 2
+ :caption: Further Topics
+
+ ../further_topics/metadata
+ ../further_topics/lenient_metadata
+ ../further_topics/lenient_maths
+ ../further_topics/ugrid/index
diff --git a/docs/src/userguide/interpolation_and_regridding.rst b/docs/src/userguide/interpolation_and_regridding.rst
index f590485606..deae4427ed 100644
--- a/docs/src/userguide/interpolation_and_regridding.rst
+++ b/docs/src/userguide/interpolation_and_regridding.rst
@@ -19,14 +19,14 @@ In Iris we refer to the available types of interpolation and regridding as
`schemes`. The following are the interpolation schemes that are currently
available in Iris:
- * linear interpolation (:class:`iris.analysis.Linear`), and
- * nearest-neighbour interpolation (:class:`iris.analysis.Nearest`).
+* linear interpolation (:class:`iris.analysis.Linear`), and
+* nearest-neighbour interpolation (:class:`iris.analysis.Nearest`).
The following are the regridding schemes that are currently available in Iris:
- * linear regridding (:class:`iris.analysis.Linear`),
- * nearest-neighbour regridding (:class:`iris.analysis.Nearest`), and
- * area-weighted regridding (:class:`iris.analysis.AreaWeighted`, first-order conservative).
+* linear regridding (:class:`iris.analysis.Linear`),
+* nearest-neighbour regridding (:class:`iris.analysis.Nearest`), and
+* area-weighted regridding (:class:`iris.analysis.AreaWeighted`, first-order conservative).
The linear, nearest-neighbor, and area-weighted regridding schemes support
lazy regridding, i.e. if the source cube has lazy data, the resulting cube
@@ -42,8 +42,8 @@ Interpolation
Interpolating a cube is achieved with the :meth:`~iris.cube.Cube.interpolate`
method. This method expects two arguments:
- #. the sample points to interpolate, and
- #. the interpolation scheme to use.
+#. the sample points to interpolate, and
+#. the interpolation scheme to use.
The result is a new cube, interpolated at the sample points.
@@ -51,9 +51,9 @@ Sample points must be defined as an iterable of ``(coord, value(s))`` pairs.
The `coord` argument can be either a coordinate name or coordinate instance.
The specified coordinate must exist on the cube being interpolated! For example:
- * coordinate names and scalar sample points: ``[('latitude', 51.48), ('longitude', 0)]``,
- * a coordinate instance and a scalar sample point: ``[(cube.coord('latitude'), 51.48)]``, and
- * a coordinate name and a NumPy array of sample points: ``[('longitude', np.linspace(-11, 2, 14))]``
+* coordinate names and scalar sample points: ``[('latitude', 51.48), ('longitude', 0)]``,
+* a coordinate instance and a scalar sample point: ``[(cube.coord('latitude'), 51.48)]``, and
+* a coordinate name and a NumPy array of sample points: ``[('longitude', np.linspace(-11, 2, 14))]``
are all examples of valid sample points.
@@ -175,11 +175,11 @@ The extrapolation mode is controlled by the ``extrapolation_mode`` keyword.
For the available interpolation schemes available in Iris, the ``extrapolation_mode``
keyword must be one of:
- * ``extrapolate`` -- the extrapolation points will be calculated by extending the gradient of the closest two points,
- * ``error`` -- a ValueError exception will be raised, notifying an attempt to extrapolate,
- * ``nan`` -- the extrapolation points will be be set to NaN,
- * ``mask`` -- the extrapolation points will always be masked, even if the source data is not a MaskedArray, or
- * ``nanmask`` -- if the source data is a MaskedArray the extrapolation points will be masked. Otherwise they will be set to NaN.
+* ``extrapolate`` -- the extrapolation points will be calculated by extending the gradient of the closest two points,
+* ``error`` -- a ValueError exception will be raised, notifying an attempt to extrapolate,
+* ``nan`` -- the extrapolation points will be be set to NaN,
+* ``mask`` -- the extrapolation points will always be masked, even if the source data is not a MaskedArray, or
+* ``nanmask`` -- if the source data is a MaskedArray the extrapolation points will be masked. Otherwise they will be set to NaN.
Using an extrapolation mode is achieved by constructing an interpolation scheme
with the extrapolation mode keyword set as required. The constructed scheme
@@ -206,8 +206,8 @@ intensive part of an interpolation is setting up the interpolator.
To cache an interpolator you must set up an interpolator scheme and call the
scheme's interpolator method. The interpolator method takes as arguments:
- #. a cube to be interpolated, and
- #. an iterable of coordinate names or coordinate instances of the coordinates that are to be interpolated over.
+#. a cube to be interpolated, and
+#. an iterable of coordinate names or coordinate instances of the coordinates that are to be interpolated over.
For example:
@@ -244,8 +244,8 @@ regridding is based on the **horizontal** grid of *another cube*.
Regridding a cube is achieved with the :meth:`cube.regrid() ` method.
This method expects two arguments:
- #. *another cube* that defines the target grid onto which the cube should be regridded, and
- #. the regridding scheme to use.
+#. *another cube* that defines the target grid onto which the cube should be regridded, and
+#. the regridding scheme to use.
.. note::
@@ -278,15 +278,15 @@ mode when defining the regridding scheme.
For the available regridding schemes in Iris, the ``extrapolation_mode`` keyword
must be one of:
- * ``extrapolate`` --
+* ``extrapolate`` --
- * for :class:`~iris.analysis.Linear` the extrapolation points will be calculated by extending the gradient of the closest two points.
- * for :class:`~iris.analysis.Nearest` the extrapolation points will take their value from the nearest source point.
+ * for :class:`~iris.analysis.Linear` the extrapolation points will be calculated by extending the gradient of the closest two points.
+ * for :class:`~iris.analysis.Nearest` the extrapolation points will take their value from the nearest source point.
- * ``nan`` -- the extrapolation points will be be set to NaN.
- * ``error`` -- a ValueError exception will be raised, notifying an attempt to extrapolate.
- * ``mask`` -- the extrapolation points will always be masked, even if the source data is not a MaskedArray.
- * ``nanmask`` -- if the source data is a MaskedArray the extrapolation points will be masked. Otherwise they will be set to NaN.
+* ``nan`` -- the extrapolation points will be be set to NaN.
+* ``error`` -- a ValueError exception will be raised, notifying an attempt to extrapolate.
+* ``mask`` -- the extrapolation points will always be masked, even if the source data is not a MaskedArray.
+* ``nanmask`` -- if the source data is a MaskedArray the extrapolation points will be masked. Otherwise they will be set to NaN.
The ``rotated_psl`` cube is defined on a limited area rotated pole grid. If we regridded
the ``rotated_psl`` cube onto the global grid as defined by the ``global_air_temp`` cube
@@ -395,8 +395,8 @@ intensive part of a regrid is setting up the regridder.
To cache a regridder you must set up a regridder scheme and call the
scheme's regridder method. The regridder method takes as arguments:
- #. a cube (that is to be regridded) defining the source grid, and
- #. a cube defining the target grid to regrid the source cube to.
+#. a cube (that is to be regridded) defining the source grid, and
+#. a cube defining the target grid to regrid the source cube to.
For example:
diff --git a/docs/src/userguide/iris_cubes.rst b/docs/src/userguide/iris_cubes.rst
index d13dee369c..29d8f3cefc 100644
--- a/docs/src/userguide/iris_cubes.rst
+++ b/docs/src/userguide/iris_cubes.rst
@@ -4,82 +4,105 @@
Iris Data Structures
====================
-The top level object in Iris is called a cube. A cube contains data and metadata about a phenomenon.
+The top level object in Iris is called a cube. A cube contains data and
+metadata about a phenomenon.
-In Iris, a cube is an interpretation of the *Climate and Forecast (CF) Metadata Conventions* whose purpose is to:
+In Iris, a cube is an interpretation of the *Climate and Forecast (CF)
+Metadata Conventions* whose purpose is to:
- *require conforming datasets to contain sufficient metadata that they are self-describing... including physical
- units if appropriate, and that each value can be located in space (relative to earth-based coordinates) and time.*
+.. panels::
+ :container: container-lg pb-3
+ :column: col-lg-12 p-2
-Whilst the CF conventions are often mentioned alongside NetCDF, Iris implements several major format importers which can take
-files of specific formats and turn them into Iris cubes. Additionally, a framework is provided which allows users
-to extend Iris' import capability to cater for specialist or unimplemented formats.
+ *require conforming datasets to contain sufficient metadata that they are
+ self-describing... including physical units if appropriate, and that each
+ value can be located in space (relative to earth-based coordinates) and
+ time.*
-A single cube describes one and only one phenomenon, always has a name, a unit and
-an n-dimensional data array to represents the cube's phenomenon. In order to locate the
-data spatially, temporally, or in any other higher-dimensional space, a collection of *coordinates*
-exist on the cube.
+
+Whilst the CF conventions are often mentioned alongside NetCDF, Iris implements
+several major format importers which can take files of specific formats and
+turn them into Iris cubes. Additionally, a framework is provided which allows
+users to extend Iris' import capability to cater for specialist or
+unimplemented formats.
+
+A single cube describes one and only one phenomenon, always has a name, a unit
+and an n-dimensional data array to represents the cube's phenomenon. In order
+to locate the data spatially, temporally, or in any other higher-dimensional
+space, a collection of *coordinates* exist on the cube.
Coordinates
===========
-A coordinate is a container to store metadata about some dimension(s) of a cube's data array and therefore,
-by definition, its phenomenon.
-
- * Each coordinate has a name and a unit.
- * When a coordinate is added to a cube, the data dimensions that it represents are also provided.
-
- * The shape of a coordinate is always the same as the shape of the associated data dimension(s) on the cube.
- * A dimension not explicitly listed signifies that the coordinate is independent of that dimension.
- * Each dimension of a coordinate must be mapped to a data dimension. The only coordinates with no mapping are
- scalar coordinates.
-
- * Depending on the underlying data that the coordinate is representing, its values may be discrete points or be
- bounded to represent interval extents (e.g. temperature at *point x* **vs** rainfall accumulation *between 0000-1200 hours*).
- * Coordinates have an attributes dictionary which can hold arbitrary extra metadata, excluding certain restricted CF names
- * More complex coordinates may contain a coordinate system which is necessary to fully interpret the values
- contained within the coordinate.
-
+A coordinate is a container to store metadata about some dimension(s) of a
+cube's data array and therefore, by definition, its phenomenon.
+
+* Each coordinate has a name and a unit.
+* When a coordinate is added to a cube, the data dimensions that it
+ represents are also provided.
+
+ * The shape of a coordinate is always the same as the shape of the
+ associated data dimension(s) on the cube.
+ * A dimension not explicitly listed signifies that the coordinate is
+ independent of that dimension.
+ * Each dimension of a coordinate must be mapped to a data dimension. The
+ only coordinates with no mapping are scalar coordinates.
+
+* Depending on the underlying data that the coordinate is representing, its
+ values may be discrete points or be bounded to represent interval extents
+ (e.g. temperature at *point x* **vs** rainfall accumulation *between
+ 0000-1200 hours*).
+* Coordinates have an attributes dictionary which can hold arbitrary extra
+ metadata, excluding certain restricted CF names
+* More complex coordinates may contain a coordinate system which is
+ necessary to fully interpret the values contained within the coordinate.
+
There are two classes of coordinates:
- **DimCoord**
-
- * Numeric
- * Monotonic
- * Representative of, at most, a single data dimension (1d)
+**DimCoord**
+
+* Numeric
+* Monotonic
+* Representative of, at most, a single data dimension (1d)
+
+**AuxCoord**
+
+* May be of any type, including strings
+* May represent multiple data dimensions (n-dimensional)
- **AuxCoord**
-
- * May be of any type, including strings
- * May represent multiple data dimensions (n-dimensional)
-
Cube
====
A cube consists of:
- * a standard name and/or a long name and an appropriate unit
- * a data array who's values are representative of the phenomenon
- * a collection of coordinates and associated data dimensions on the cube's data array, which are split into two separate lists:
+* a standard name and/or a long name and an appropriate unit
+* a data array who's values are representative of the phenomenon
+* a collection of coordinates and associated data dimensions on the cube's
+ data array, which are split into two separate lists:
+
+ * *dimension coordinates* - DimCoords which uniquely map to exactly one
+ data dimension, ordered by dimension.
+ * *auxiliary coordinates* - DimCoords or AuxCoords which map to as many
+ data dimensions as the coordinate has dimensions.
- * *dimension coordinates* - DimCoords which uniquely map to exactly one data dimension, ordered by dimension.
- * *auxiliary coordinates* - DimCoords or AuxCoords which map to as many data dimensions as the coordinate has dimensions.
-
- * an attributes dictionary which, other than some protected CF names, can hold arbitrary extra metadata.
- * a list of cell methods to represent operations which have already been applied to the data (e.g. "mean over time")
- * a list of coordinate "factories" used for deriving coordinates from the values of other coordinates in the cube
+* an attributes dictionary which, other than some protected CF names, can
+ hold arbitrary extra metadata.
+* a list of cell methods to represent operations which have already been
+ applied to the data (e.g. "mean over time")
+* a list of coordinate "factories" used for deriving coordinates from the
+ values of other coordinates in the cube
Cubes in Practice
-----------------
-
A Simple Cube Example
=====================
-Suppose we have some gridded data which has 24 air temperature readings (in Kelvin) which is located at
-4 different longitudes, 2 different latitudes and 3 different heights. Our data array can be represented pictorially:
+Suppose we have some gridded data which has 24 air temperature readings
+(in Kelvin) which is located at 4 different longitudes, 2 different latitudes
+and 3 different heights. Our data array can be represented pictorially:
.. image:: multi_array.png
@@ -87,61 +110,66 @@ Where dimensions 0, 1, and 2 have lengths 3, 2 and 4 respectively.
The Iris cube to represent this data would consist of:
- * a standard name of ``air_temperature`` and a unit of ``kelvin``
- * a data array of shape ``(3, 2, 4)``
- * a coordinate, mapping to dimension 0, consisting of:
-
- * a standard name of ``height`` and unit of ``meters``
- * an array of length 3 representing the 3 ``height`` points
-
- * a coordinate, mapping to dimension 1, consisting of:
-
- * a standard name of ``latitude`` and unit of ``degrees``
- * an array of length 2 representing the 2 latitude points
- * a coordinate system such that the ``latitude`` points could be fully located on the globe
-
- * a coordinate, mapping to dimension 2, consisting of:
-
- * a standard name of ``longitude`` and unit of ``degrees``
- * an array of length 4 representing the 4 longitude points
- * a coordinate system such that the ``longitude`` points could be fully located on the globe
-
+* a standard name of ``air_temperature`` and a unit of ``kelvin``
+* a data array of shape ``(3, 2, 4)``
+* a coordinate, mapping to dimension 0, consisting of:
+
+ * a standard name of ``height`` and unit of ``meters``
+ * an array of length 3 representing the 3 ``height`` points
+* a coordinate, mapping to dimension 1, consisting of:
+ * a standard name of ``latitude`` and unit of ``degrees``
+ * an array of length 2 representing the 2 latitude points
+ * a coordinate system such that the ``latitude`` points could be fully
+ located on the globe
-Pictorially the cube has taken on more information than a simple array:
+* a coordinate, mapping to dimension 2, consisting of:
+
+ * a standard name of ``longitude`` and unit of ``degrees``
+ * an array of length 4 representing the 4 longitude points
+ * a coordinate system such that the ``longitude`` points could be fully
+ located on the globe
+
+Pictorially the cube has taken on more information than a simple array:
.. image:: multi_array_to_cube.png
-Additionally further information may be optionally attached to the cube.
-For example, it is possible to attach any of the following:
-
- * a coordinate, not mapping to any data dimensions, consisting of:
-
- * a standard name of ``time`` and unit of ``days since 2000-01-01 00:00``
- * a data array of length 1 representing the time that the data array is valid for
-
- * an auxiliary coordinate, mapping to dimensions 1 and 2, consisting of:
-
- * a long name of ``place name`` and no unit
- * a 2d string array of shape ``(2, 4)`` with the names of the 8 places that the lat/lons correspond to
-
- * an auxiliary coordinate "factory", which can derive its own mapping, consisting of:
-
- * a standard name of ``height`` and a unit of ``feet``
- * knowledge of how data values for this coordinate can be calculated given the ``height in meters`` coordinate
-
- * a cell method of "mean" over "ensemble" to indicate that the data has been meaned over
- a collection of "ensembles" (i.e. multiple model runs).
+Additionally further information may be optionally attached to the cube.
+For example, it is possible to attach any of the following:
+
+* a coordinate, not mapping to any data dimensions, consisting of:
+
+ * a standard name of ``time`` and unit of ``days since 2000-01-01 00:00``
+ * a data array of length 1 representing the time that the data array is
+ valid for
+
+* an auxiliary coordinate, mapping to dimensions 1 and 2, consisting of:
+
+ * a long name of ``place name`` and no unit
+ * a 2d string array of shape ``(2, 4)`` with the names of the 8 places
+ that the lat/lons correspond to
+
+* an auxiliary coordinate "factory", which can derive its own mapping,
+ consisting of:
+
+ * a standard name of ``height`` and a unit of ``feet``
+ * knowledge of how data values for this coordinate can be calculated
+ given the ``height in meters`` coordinate
+
+* a cell method of "mean" over "ensemble" to indicate that the data has been
+ meaned over a collection of "ensembles" (i.e. multiple model runs).
Printing a Cube
===============
-Every Iris cube can be printed to screen as you will see later in the user guide. It is worth familiarising yourself with the
-output as this is the quickest way of inspecting the contents of a cube. Here is the result of printing a real life cube:
+Every Iris cube can be printed to screen as you will see later in the user
+guide. It is worth familiarising yourself with the output as this is the
+quickest way of inspecting the contents of a cube. Here is the result of
+printing a real life cube:
.. _hybrid_cube_printout:
@@ -150,7 +178,7 @@ output as this is the quickest way of inspecting the contents of a cube. Here is
import iris
filename = iris.sample_data_path('uk_hires.pp')
- # NOTE: Every time the output of this cube changes, the full list of deductions below should be re-assessed.
+ # NOTE: Every time the output of this cube changes, the full list of deductions below should be re-assessed.
print(iris.load_cube(filename, 'air_potential_temperature'))
.. testoutput::
@@ -178,16 +206,22 @@ output as this is the quickest way of inspecting the contents of a cube. Here is
Using this output we can deduce that:
- * The cube represents air potential temperature.
- * There are 4 data dimensions, and the data has a shape of ``(3, 7, 204, 187)``
- * The 4 data dimensions are mapped to the ``time``, ``model_level_number``,
- ``grid_latitude``, ``grid_longitude`` coordinates respectively
- * There are three 1d auxiliary coordinates and one 2d auxiliary (``surface_altitude``)
- * There is a single ``altitude`` derived coordinate, which spans 3 data dimensions
- * There are 7 distinct values in the "model_level_number" coordinate. Similar inferences can
- be made for the other dimension coordinates.
- * There are 7, not necessarily distinct, values in the ``level_height`` coordinate.
- * There is a single ``forecast_reference_time`` scalar coordinate representing the entire cube.
- * The cube has one further attribute relating to the phenomenon.
- In this case the originating file format, PP, encodes information in a STASH code which in some cases can
- be useful for identifying advanced experiment information relating to the phenomenon.
+* The cube represents air potential temperature.
+* There are 4 data dimensions, and the data has a shape of ``(3, 7, 204, 187)``
+* The 4 data dimensions are mapped to the ``time``, ``model_level_number``,
+ ``grid_latitude``, ``grid_longitude`` coordinates respectively
+* There are three 1d auxiliary coordinates and one 2d auxiliary
+ (``surface_altitude``)
+* There is a single ``altitude`` derived coordinate, which spans 3 data
+ dimensions
+* There are 7 distinct values in the "model_level_number" coordinate. Similar
+ inferences can
+ be made for the other dimension coordinates.
+* There are 7, not necessarily distinct, values in the ``level_height``
+ coordinate.
+* There is a single ``forecast_reference_time`` scalar coordinate representing
+ the entire cube.
+* The cube has one further attribute relating to the phenomenon.
+ In this case the originating file format, PP, encodes information in a STASH
+ code which in some cases can be useful for identifying advanced experiment
+ information relating to the phenomenon.
diff --git a/docs/src/userguide/loading_iris_cubes.rst b/docs/src/userguide/loading_iris_cubes.rst
index 9e9c343300..33ad932d70 100644
--- a/docs/src/userguide/loading_iris_cubes.rst
+++ b/docs/src/userguide/loading_iris_cubes.rst
@@ -39,15 +39,15 @@ This shows that there were 2 cubes as a result of loading the file, they were:
The ``surface_altitude`` cube was 2 dimensional with:
- * the two dimensions have extents of 204 and 187 respectively and are
- represented by the ``grid_latitude`` and ``grid_longitude`` coordinates.
+* the two dimensions have extents of 204 and 187 respectively and are
+ represented by the ``grid_latitude`` and ``grid_longitude`` coordinates.
The ``air_potential_temperature`` cubes were 4 dimensional with:
- * the same length ``grid_latitude`` and ``grid_longitude`` dimensions as
- ``surface_altitide``
- * a ``time`` dimension of length 3
- * a ``model_level_number`` dimension of length 7
+* the same length ``grid_latitude`` and ``grid_longitude`` dimensions as
+ ``surface_altitide``
+* a ``time`` dimension of length 3
+* a ``model_level_number`` dimension of length 7
.. note::
@@ -55,7 +55,7 @@ The ``air_potential_temperature`` cubes were 4 dimensional with:
(even if it only contains one :class:`iris.cube.Cube` - see
:ref:`strict-loading`). Anything that can be done with a Python
:class:`list` can be done with an :class:`iris.cube.CubeList`.
-
+
The order of this list should not be relied upon. Ways of loading a
specific cube or cubes are covered in :ref:`constrained-loading` and
:ref:`strict-loading`.
diff --git a/docs/src/userguide/merge_and_concat.rst b/docs/src/userguide/merge_and_concat.rst
index e8425df5ec..08c3ce9711 100644
--- a/docs/src/userguide/merge_and_concat.rst
+++ b/docs/src/userguide/merge_and_concat.rst
@@ -22,14 +22,14 @@ result in fewer cubes as output. The following diagram illustrates the two proce
There is one major difference between the ``merge`` and ``concatenate`` processes.
- * The ``merge`` process combines multiple input cubes into a
- single resultant cube with new dimensions created from the
- *scalar coordinate values* of the input cubes.
-
- * The ``concatenate`` process combines multiple input cubes into a
- single resultant cube with the same *number of dimensions* as the input cubes,
- but with the length of one or more dimensions extended by *joining together
- sequential dimension coordinates*.
+* The ``merge`` process combines multiple input cubes into a
+ single resultant cube with new dimensions created from the
+ *scalar coordinate values* of the input cubes.
+
+* The ``concatenate`` process combines multiple input cubes into a
+ single resultant cube with the same *number of dimensions* as the input cubes,
+ but with the length of one or more dimensions extended by *joining together
+ sequential dimension coordinates*.
Let's imagine 28 individual cubes representing the
temperature at a location ``(y, x)``; one cube for each day of February. We can use
diff --git a/docs/src/userguide/plotting_a_cube.rst b/docs/src/userguide/plotting_a_cube.rst
index cfb3445d9b..a2334367c5 100644
--- a/docs/src/userguide/plotting_a_cube.rst
+++ b/docs/src/userguide/plotting_a_cube.rst
@@ -101,15 +101,15 @@ see :py:func:`matplotlib.pyplot.savefig`).
Some of the formats which are supported by **plt.savefig**:
- ====== ====== ======================================================================
- Format Type Description
- ====== ====== ======================================================================
- EPS Vector Encapsulated PostScript
- PDF Vector Portable Document Format
- PNG Raster Portable Network Graphics, a format with a lossless compression method
- PS Vector PostScript, ideal for printer output
- SVG Vector Scalable Vector Graphics, XML based
- ====== ====== ======================================================================
+====== ====== ======================================================================
+Format Type Description
+====== ====== ======================================================================
+EPS Vector Encapsulated PostScript
+PDF Vector Portable Document Format
+PNG Raster Portable Network Graphics, a format with a lossless compression method
+PS Vector PostScript, ideal for printer output
+SVG Vector Scalable Vector Graphics, XML based
+====== ====== ======================================================================
******************
Iris Cube Plotting
@@ -125,12 +125,12 @@ wrapper functions.
As a rule of thumb:
- * if you wish to do a visualisation with a cube, use ``iris.plot`` or
- ``iris.quickplot``.
- * if you wish to show, save or manipulate **any** visualisation,
- including ones created with Iris, use ``matplotlib.pyplot``.
- * if you wish to create a non cube visualisation, also use
- ``matplotlib.pyplot``.
+* if you wish to do a visualisation with a cube, use ``iris.plot`` or
+ ``iris.quickplot``.
+* if you wish to show, save or manipulate **any** visualisation,
+ including ones created with Iris, use ``matplotlib.pyplot``.
+* if you wish to create a non cube visualisation, also use
+ ``matplotlib.pyplot``.
The ``iris.quickplot`` module is exactly the same as the ``iris.plot`` module,
except that ``quickplot`` will add a title, x and y labels and a colorbar
diff --git a/docs/src/userguide/real_and_lazy_data.rst b/docs/src/userguide/real_and_lazy_data.rst
index 0bc1846457..9d66a2f086 100644
--- a/docs/src/userguide/real_and_lazy_data.rst
+++ b/docs/src/userguide/real_and_lazy_data.rst
@@ -140,11 +140,11 @@ Core Data
Cubes have the concept of "core data". This returns the cube's data in its
current state:
- * If a cube has lazy data, calling the cube's :meth:`~iris.cube.Cube.core_data` method
- will return the cube's lazy dask array. Calling the cube's
- :meth:`~iris.cube.Cube.core_data` method **will never realise** the cube's data.
- * If a cube has real data, calling the cube's :meth:`~iris.cube.Cube.core_data` method
- will return the cube's real NumPy array.
+* If a cube has lazy data, calling the cube's :meth:`~iris.cube.Cube.core_data` method
+ will return the cube's lazy dask array. Calling the cube's
+ :meth:`~iris.cube.Cube.core_data` method **will never realise** the cube's data.
+* If a cube has real data, calling the cube's :meth:`~iris.cube.Cube.core_data` method
+ will return the cube's real NumPy array.
For example::
@@ -174,14 +174,14 @@ In the same way that Iris cubes contain a data array, Iris coordinates contain a
points array and an optional bounds array.
Coordinate points and bounds arrays can also be real or lazy:
- * A :class:`~iris.coords.DimCoord` will only ever have **real** points and bounds
- arrays because of monotonicity checks that realise lazy arrays.
- * An :class:`~iris.coords.AuxCoord` can have **real or lazy** points and bounds.
- * An :class:`~iris.aux_factory.AuxCoordFactory` (or derived coordinate)
- can have **real or lazy** points and bounds. If all of the
- :class:`~iris.coords.AuxCoord` instances used to construct the derived coordinate
- have real points and bounds then the derived coordinate will have real points
- and bounds, otherwise the derived coordinate will have lazy points and bounds.
+* A :class:`~iris.coords.DimCoord` will only ever have **real** points and bounds
+ arrays because of monotonicity checks that realise lazy arrays.
+* An :class:`~iris.coords.AuxCoord` can have **real or lazy** points and bounds.
+* An :class:`~iris.aux_factory.AuxCoordFactory` (or derived coordinate)
+ can have **real or lazy** points and bounds. If all of the
+ :class:`~iris.coords.AuxCoord` instances used to construct the derived coordinate
+ have real points and bounds then the derived coordinate will have real points
+ and bounds, otherwise the derived coordinate will have lazy points and bounds.
Iris cubes and coordinates have very similar interfaces, which extends to accessing
coordinates' lazy points and bounds:
diff --git a/docs/src/voted_issues.rst b/docs/src/voted_issues.rst
index 473af3351e..7d983448b9 100644
--- a/docs/src/voted_issues.rst
+++ b/docs/src/voted_issues.rst
@@ -1,6 +1,6 @@
.. include:: common_links.inc
-.. _voted_issues:
+.. _voted_issues_top:
Voted Issues
============
diff --git a/docs/src/whatsnew/3.2.rst b/docs/src/whatsnew/3.2.rst
index 4a82b24857..63deb5d459 100644
--- a/docs/src/whatsnew/3.2.rst
+++ b/docs/src/whatsnew/3.2.rst
@@ -289,7 +289,7 @@ v3.2.1 (11 Mar 2022)
#. `@rcomer`_ updated the "Plotting Wind Direction Using Quiver" Gallery
example. (:pull:`4120`)
-#. `@trexfeathers`_ included `Iris GitHub Discussions`_ in
+#. `@trexfeathers`_ included Iris `GitHub Discussions`_ in
:ref:`get involved `. (:pull:`4307`)
#. `@wjbenfold`_ improved readability in :ref:`userguide interpolation
diff --git a/docs/src/whatsnew/dev.rst b/docs/src/whatsnew/dev.rst
deleted file mode 100644
index 843815b46b..0000000000
--- a/docs/src/whatsnew/dev.rst
+++ /dev/null
@@ -1,137 +0,0 @@
-.. include:: ../common_links.inc
-
-|iris_version| |build_date| [unreleased]
-****************************************
-
-This document explains the changes made to Iris for this release
-(:doc:`View all changes `.)
-
-
-.. dropdown:: :opticon:`report` |iris_version| Release Highlights
- :container: + shadow
- :title: text-primary text-center font-weight-bold
- :body: bg-light
- :animate: fade-in
- :open:
-
- The highlights for this minor release of Iris include:
-
- * N/A
-
- And finally, get in touch with us on :issue:`GitHub` if you have
- any issues or feature requests for improving Iris. Enjoy!
-
-
-📢 Announcements
-================
-
-#. N/A
-
-
-✨ Features
-===========
-
-#. `@wjbenfold`_ added support for ``false_easting`` and ``false_northing`` to
- :class:`~iris.coord_system.Mercator`. (:issue:`3107`, :pull:`4524`)
-
-#. `@rcomer`_ implemented lazy aggregation for the
- :obj:`iris.analysis.PERCENTILE` aggregator. (:pull:`3901`)
-
-#. `@pp-mo`_ fixed cube arithmetic operation for cubes with meshes.
- (:issue:`4454`, :pull:`4651`)
-
-
-🐛 Bugs Fixed
-=============
-
-#. `@rcomer`_ reverted part of the change from :pull:`3906` so that
- :func:`iris.plot.plot` no longer defaults to placing a "Y" coordinate (e.g.
- latitude) on the y-axis of the plot. (:issue:`4493`, :pull:`4601`)
-
-#. `@rcomer`_ enabled passing of scalar objects to :func:`~iris.plot.plot` and
- :func:`~iris.plot.scatter`. (:pull:`4616`)
-
-#. `@rcomer`_ fixed :meth:`~iris.cube.Cube.aggregated_by` with `mdtol` for 1D
- cubes where an aggregated section is entirely masked, reported at
- :issue:`3190`. (:pull:`4246`)
-
-#. `@rcomer`_ ensured that a :class:`matplotlib.axes.Axes`'s position is preserved
- when Iris replaces it with a :class:`cartopy.mpl.geoaxes.GeoAxes`, fixing
- :issue:`1157`. (:pull:`4273`)
-
-#. `@rcomer`_ fixed :meth:`~iris.coords.Coord.nearest_neighbour_index` for edge
- cases where the requested point is float and the coordinate has integer
- bounds, reported at :issue:`2969`. (:pull:`4245`)
-
-#. `@rcomer`_ modified bounds setting on :obj:`~iris.coords.DimCoord` instances
- so that the order of the cell bounds is automatically reversed
- to match the coordinate's direction if necessary. This is consistent with
- the `Bounds for 1-D coordinate variables` subsection of the `Cell Boundaries`_
- section of the CF Conventions and ensures that contiguity is preserved if a
- coordinate's direction is reversed. (:issue:`3249`, :issue:`423`,
- :issue:`4078`, :issue:`3756`, :pull:`4466`)
-
-
-💣 Incompatible Changes
-=======================
-
-#. N/A
-
-
-🚀 Performance Enhancements
-===========================
-
-#. N/A
-
-
-🔥 Deprecations
-===============
-
-#. N/A
-
-
-🔗 Dependencies
-===============
-
-#. `@rcomer`_ introduced the ``nc-time-axis >=1.4`` minimum pin, reflecting that
- we no longer use the deprecated :class:`nc_time_axis.CalendarDateTime`
- when plotting against time coordinates. (:pull:`4584`)
-
-
-📚 Documentation
-================
-
-#. `@tkknight`_ added a page to show the issues that have been voted for. See
- :ref:`voted_issues`. (:issue:`3307`, :pull:`4617`)
-#. `@wjbenfold`_ added a note about fixing proxy URLs in lockfiles generated
- because dependencies have changed. (:pull:`4666`)
-#. `@lbdreyer`_ moved most of the User Guide's :class:`iris.Constraint` examples
- from :ref:`loading_iris_cubes` to :ref:`cube_extraction` and added an
- example of constraining on bounded time. (:pull:`4656`)
-
-
-💼 Internal
-===========
-
-#. `@trexfeathers`_ and `@pp-mo`_ finished implementing a mature benchmarking
- infrastructure (see :ref:`contributing.benchmarks`), building on 2 hard
- years of lessons learned 🎉. (:pull:`4477`, :pull:`4562`, :pull:`4571`,
- :pull:`4583`, :pull:`4621`)
-#. `@wjbenfold`_ used the aforementioned benchmarking infrastructure to
- introduce deep (large 3rd dimension) loading and realisation benchmarks.
- (:pull:`4654`)
-#. `@wjbenfold`_ made :func:`iris.tests.stock.simple_1d` respect the
- ``with_bounds`` argument. (:pull:`4658`)
-
-
-.. comment
- Whatsnew author names (@github name) in alphabetical order. Note that,
- core dev names are automatically included by the common_links.inc:
-
-
-
-
-.. comment
- Whatsnew resources in alphabetical order:
-
-.. _Cell Boundaries: https://cfconventions.org/Data/cf-conventions/cf-conventions-1.9/cf-conventions.html#cell-boundaries
diff --git a/docs/src/whatsnew/index.rst b/docs/src/whatsnew/index.rst
index 7e0829da5b..949d727a99 100644
--- a/docs/src/whatsnew/index.rst
+++ b/docs/src/whatsnew/index.rst
@@ -10,7 +10,7 @@ Iris versions.
.. toctree::
:maxdepth: 1
- dev.rst
+ latest.rst
3.2.rst
3.1.rst
3.0.rst
diff --git a/docs/src/whatsnew/latest.rst b/docs/src/whatsnew/latest.rst
deleted file mode 120000
index 56aebe92dd..0000000000
--- a/docs/src/whatsnew/latest.rst
+++ /dev/null
@@ -1 +0,0 @@
-dev.rst
\ No newline at end of file
diff --git a/docs/src/whatsnew/latest.rst b/docs/src/whatsnew/latest.rst
new file mode 100644
index 0000000000..52313d5d81
--- /dev/null
+++ b/docs/src/whatsnew/latest.rst
@@ -0,0 +1,145 @@
+.. include:: ../common_links.inc
+
+|iris_version| |build_date| [unreleased]
+****************************************
+
+This document explains the changes made to Iris for this release
+(:doc:`View all changes `.)
+
+
+.. dropdown:: :opticon:`report` |iris_version| Release Highlights
+ :container: + shadow
+ :title: text-primary text-center font-weight-bold
+ :body: bg-light
+ :animate: fade-in
+ :open:
+
+ The highlights for this minor release of Iris include:
+
+ * N/A
+
+ And finally, get in touch with us on :issue:`GitHub` if you have
+ any issues or feature requests for improving Iris. Enjoy!
+
+
+📢 Announcements
+================
+
+#. N/A
+
+
+✨ Features
+===========
+
+#. `@wjbenfold`_ added support for ``false_easting`` and ``false_northing`` to
+ :class:`~iris.coord_system.Mercator`. (:issue:`3107`, :pull:`4524`)
+
+#. `@rcomer`_ implemented lazy aggregation for the
+ :obj:`iris.analysis.PERCENTILE` aggregator. (:pull:`3901`)
+
+#. `@pp-mo`_ fixed cube arithmetic operation for cubes with meshes.
+ (:issue:`4454`, :pull:`4651`)
+
+
+🐛 Bugs Fixed
+=============
+
+#. `@rcomer`_ reverted part of the change from :pull:`3906` so that
+ :func:`iris.plot.plot` no longer defaults to placing a "Y" coordinate (e.g.
+ latitude) on the y-axis of the plot. (:issue:`4493`, :pull:`4601`)
+
+#. `@rcomer`_ enabled passing of scalar objects to :func:`~iris.plot.plot` and
+ :func:`~iris.plot.scatter`. (:pull:`4616`)
+
+#. `@rcomer`_ fixed :meth:`~iris.cube.Cube.aggregated_by` with `mdtol` for 1D
+ cubes where an aggregated section is entirely masked, reported at
+ :issue:`3190`. (:pull:`4246`)
+
+#. `@rcomer`_ ensured that a :class:`matplotlib.axes.Axes`'s position is preserved
+ when Iris replaces it with a :class:`cartopy.mpl.geoaxes.GeoAxes`, fixing
+ :issue:`1157`. (:pull:`4273`)
+
+#. `@rcomer`_ fixed :meth:`~iris.coords.Coord.nearest_neighbour_index` for edge
+ cases where the requested point is float and the coordinate has integer
+ bounds, reported at :issue:`2969`. (:pull:`4245`)
+
+#. `@rcomer`_ modified bounds setting on :obj:`~iris.coords.DimCoord` instances
+ so that the order of the cell bounds is automatically reversed
+ to match the coordinate's direction if necessary. This is consistent with
+ the `Bounds for 1-D coordinate variables` subsection of the `Cell Boundaries`_
+ section of the CF Conventions and ensures that contiguity is preserved if a
+ coordinate's direction is reversed. (:issue:`3249`, :issue:`423`,
+ :issue:`4078`, :issue:`3756`, :pull:`4466`)
+
+
+💣 Incompatible Changes
+=======================
+
+#. N/A
+
+
+🚀 Performance Enhancements
+===========================
+
+#. N/A
+
+
+🔥 Deprecations
+===============
+
+#. N/A
+
+
+🔗 Dependencies
+===============
+
+#. `@rcomer`_ introduced the ``nc-time-axis >=1.4`` minimum pin, reflecting that
+ we no longer use the deprecated :class:`nc_time_axis.CalendarDateTime`
+ when plotting against time coordinates. (:pull:`4584`)
+
+
+📚 Documentation
+================
+
+#. `@tkknight`_ added a page to show the issues that have been voted for. See
+ :ref:`voted_issues_top`. (:issue:`3307`, :pull:`4617`)
+
+#. `@wjbenfold`_ added a note about fixing proxy URLs in lockfiles generated
+ because dependencies have changed. (:pull:`4666`)
+
+#. `@lbdreyer`_ moved most of the User Guide's :class:`iris.Constraint` examples
+ from :ref:`loading_iris_cubes` to :ref:`cube_extraction` and added an
+ example of constraining on bounded time. (:pull:`4656`)
+
+#. `@tkknight`_ adopted the `PyData Sphinx Theme`_ for the documentation.
+ (:discussion:`4344`, :pull:`4661`)
+
+
+💼 Internal
+===========
+
+#. `@trexfeathers`_ and `@pp-mo`_ finished implementing a mature benchmarking
+ infrastructure (see :ref:`contributing.benchmarks`), building on 2 hard
+ years of lessons learned 🎉. (:pull:`4477`, :pull:`4562`, :pull:`4571`,
+ :pull:`4583`, :pull:`4621`)
+
+#. `@wjbenfold`_ used the aforementioned benchmarking infrastructure to
+ introduce deep (large 3rd dimension) loading and realisation benchmarks.
+ (:pull:`4654`)
+
+#. `@wjbenfold`_ made :func:`iris.tests.stock.simple_1d` respect the
+ ``with_bounds`` argument. (:pull:`4658`)
+
+
+.. comment
+ Whatsnew author names (@github name) in alphabetical order. Note that,
+ core dev names are automatically included by the common_links.inc:
+
+
+
+
+.. comment
+ Whatsnew resources in alphabetical order:
+
+.. _Cell Boundaries: https://cfconventions.org/Data/cf-conventions/cf-conventions-1.9/cf-conventions.html#cell-boundaries
+.. _PyData Sphinx Theme: https://pydata-sphinx-theme.readthedocs.io/en/stable/index.html
diff --git a/docs/src/whatsnew/dev.rst.template b/docs/src/whatsnew/latest.rst.template
similarity index 100%
rename from docs/src/whatsnew/dev.rst.template
rename to docs/src/whatsnew/latest.rst.template
diff --git a/docs/src/why_iris.rst b/docs/src/why_iris.rst
new file mode 100644
index 0000000000..63a515f68e
--- /dev/null
+++ b/docs/src/why_iris.rst
@@ -0,0 +1,44 @@
+.. _why_iris:
+
+Why Iris
+========
+
+**A powerful, format-agnostic, community-driven Python package for analysing
+and visualising Earth science data.**
+
+Iris implements a data model based on the `CF conventions `_
+giving you a powerful, format-agnostic interface for working with your data.
+It excels when working with multi-dimensional Earth Science data, where tabular
+representations become unwieldy and inefficient.
+
+`CF Standard names `_,
+`units `_, and coordinate metadata
+are built into Iris, giving you a rich and expressive interface for maintaining
+an accurate representation of your data. Its treatment of data and
+associated metadata as first-class objects includes:
+
+.. rst-class:: squarelist
+
+* visualisation interface based on `matplotlib
- - {% if menu_links_name %} - {{ menu_links_name }} - {% else %} - External links - {% endif %} - -
--
- {% for text, link in menu_links %}
-
- {{ text }} - {% endfor %} -