Finalise whatsnew and version string; update CI to fix. (#4316)

* Finalise whatsnew and version string. * cartopy feature download (#4304) * Fix broken ABF link * add cartopy downloader utility * update netcdf4-python link * explicitly specify features to download for ci * added whatsnew entry * update utility help * utility tidy * tidy utility * copy with cartopy script rename * update whatsnew to clarify as dev tool * push fix to cartopy * use cartopy master * Fix typo * Update copyright.rst * Update conf.py * Review changes. Co-authored-by: Bill Little <bill.james.little@gmail.com> Co-authored-by: Bill Little <bill.little@metoffice.gov.uk>
SciTools · Sep 16, 2021 · b7ed8fd · b7ed8fd
1 parent c58a592
commit b7ed8fd
Show file tree

Hide file tree

Showing 9 changed files with 52 additions and 19 deletions.
diff --git a/.cirrus.yml b/.cirrus.yml
@@ -26,7 +26,7 @@ env:
   # Maximum cache period (in weeks) before forcing a new cache upload.
   CACHE_PERIOD: "2"
   # Increment the build number to force new cartopy cache upload.
-  CARTOPY_CACHE_BUILD: "0"
+  CARTOPY_CACHE_BUILD: "3"
   # Increment the build number to force new conda cache upload.
   CONDA_CACHE_BUILD: "0"
   # Increment the build number to force new nox cache upload.
@@ -72,6 +72,14 @@ linux_task_template: &LINUX_TASK_TEMPLATE
     fingerprint_script:
       - echo "${CIRRUS_OS}"
       - echo "$(date +%Y).$(expr $(date +%U) / ${CACHE_PERIOD}):${CARTOPY_CACHE_BUILD}"
+    populate_script:
+      - conda create --quiet --name cartopy-cache cartopy
+      - source ${HOME}/miniconda/etc/profile.d/conda.sh >/dev/null 2>&1
+      - conda activate cartopy-cache >/dev/null 2>&1
+      - cd $(mktemp -d)
+      - wget --quiet https://raw.githubusercontent.com/SciTools/cartopy/master/tools/cartopy_feature_download.py
+      - python cartopy_feature_download.py physical --output ${HOME}/.local/share/cartopy --no-warn
+      - conda deactivate >/dev/null 2>&1
   nox_cache:
     folder: ${CIRRUS_WORKING_DIR}/.nox
     reupload_on_changes: true

diff --git a/docs/src/common_links.inc b/docs/src/common_links.inc
@@ -2,6 +2,7 @@
     Common resources in alphabetical order:
 
 .. _black: https://black.readthedocs.io/en/stable/
+.. _cartopy: https://github.com/SciTools/cartopy
 .. _.cirrus.yml: https://github.com/SciTools/iris/blob/main/.cirrus.yml
 .. _flake8: https://flake8.pycqa.org/en/stable/
 .. _.flake8.yml: https://github.com/SciTools/iris/blob/main/.flake8

diff --git a/docs/src/conf.py b/docs/src/conf.py
@@ -304,6 +304,7 @@ def _dotv(version):
     "http://www.wmo.int/pages/prog/www/DPFS/documents/485_Vol_I_en_colour.pdf",
     "https://software.ac.uk/how-cite-software",
     "http://www.esrl.noaa.gov/psd/data/gridded/conventions/cdc_netcdf_standard.shtml",
+    "https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/",
 ]
 
 # list of sources to exclude from the build.

diff --git a/docs/src/copyright.rst b/docs/src/copyright.rst
@@ -31,8 +31,8 @@ are licensed under the UK's Open Government Licence:
     (C) British Crown Copyright |copyright_years|
 
     You may use and re-use the information featured on this website (not including logos) free of 
-    charge in any format or medium, under the terms of the 
-    `Open Government Licence <http://reference.data.gov.uk/id/open-government-licence>`_. 
+    charge in any format or medium, under the terms of the
+    `Open Government Licence <https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/>`_.
     We encourage users to establish hypertext links to this website.
 
     Any email enquiries regarding the use and re-use of this information resource should be 

diff --git a/docs/src/whatsnew/1.3.rst b/docs/src/whatsnew/1.3.rst
@@ -34,8 +34,8 @@ Loading ABF/ABL Files
 ---------------------
 
 Support for the ABF and ABL file formats (as
-`defined <http://cliveg.bu.edu/modismisr/lai3g-fpar3g.html>`_ by the
-climate and vegetation research group of Boston University), is
+`defined <https://nasanex.s3.amazonaws.com/AVHRR/GIMMS/LAI3G/00README_V01.pdf>`_
+by the climate and vegetation research group of Boston University), is
 currently provided under the "experimental" system. As such, ABF/ABL
 file detection is not automatically enabled.
 

diff --git a/docs/src/whatsnew/3.1.rst b/docs/src/whatsnew/3.1.rst
@@ -1,7 +1,7 @@
 .. include:: ../common_links.inc
 
-v3.1 (17 Aug 2021) [unreleased]
-*******************************
+v3.1 (16 Sep 2021)
+******************
 
 This document explains the changes made to Iris for this release
 (:doc:`View all changes <index>`.)
@@ -16,9 +16,14 @@ This document explains the changes made to Iris for this release
 
    The highlights for this minor release of Iris include:
 
-   * We've dropped support for `Python 3.6`_
-   * Updated formatting of cube printouts.
-   * Updated developer guide documentation.
+   * Much faster import times, from minimised loading of submodules.
+     However, note that this may break existing code which does not declare all imports.
+     See :ref:`minimised imports <minimised_imports>`.
+   * Speedup for loading single phenomena from netcdf.  See :ref:`netcdf load speedup <fast_nc_load>`.
+   * We've dropped support for `Python 3.6`_.  See :ref:`minimum Python version 3.7 <no_py36>`.
+   * Updated formatting of cube printouts.  See :ref:`new-style cube printouts <newstyle_cube_print>`.
+   * Multiple improvements to developer guide documentation.
+     See entries in the :ref:`"Documentation" section <docs_section>`, below.
 
    And finally, get in touch with us on `GitHub`_ if you have any issues or
    feature requests for improving Iris. Enjoy!
@@ -61,6 +66,8 @@ This document explains the changes made to Iris for this release
 #. `@Badboy-16`_ implemented a ``CubeList.copy()`` method to return a
    ``CubeList`` object instead of a ``list``. (:pull:`4094`)
 
+   .. _newstyle_cube_print:
+
 #. `@pp-mo`_ and `@trexfeathers`_ reformatted :meth:`iris.cube.Cube.summary`,
    (which is used for ``print(Cube)``); putting
    :attr:`~iris.cube.Cube.cell_methods` before
@@ -97,6 +104,8 @@ This document explains the changes made to Iris for this release
 🚀 Performance Enhancements
 ===========================
 
+.. _isort_adopt:
+
 #. `@bjlittle`_ added support for automated ``import`` linting with `isort`_, which
    also includes significant speed-ups for Iris imports. (:pull:`4174`)
 
@@ -106,22 +115,33 @@ This document explains the changes made to Iris for this release
    :class:`~iris.coords.AuxCoord`, :class:`~iris.coords.CellMeasure`, and
    :class:`~iris.cube.Cube` instances. (:pull:`4227`)
 
+   .. _fast_nc_load:
+
 #. `@pp-mo`_ and `@lbdreyer`_ optimised loading netcdf files, resulting in a
-   speed up when loading with a single :func:`~iris.NameConstraint`. Note, this
-   optimisation only applies when matching on standard name, long name or
+   speed up when loading with a single :func:`~iris.NameConstraint`.
+
+   For example, ``cube = iris.load('x.nc', NameConstraint('air_temperature'))``.
+
+   Note that this optimisation only applies when matching on standard name, long name or
    NetCDF variable name, not when matching on STASH.
    (:pull:`4176`)
 
 💣 Incompatible Changes
 =======================
 
-#. N/A
+.. _minimised_imports:
 
+#. The :ref:`adoption of 'isort' <isort_adopt>` has significantly reduced the import time of Iris packages.
 
-🔥 Deprecations
-===============
+   However, this may break existing code which, for convenience, relies on some subpackages being imported implicitly
+   (as some, but not all, previously were).
+
+   For example: ``import iris; print(iris.cube.Cube)``.
 
-#. N/A
+   This style is essentially unsafe, and in this case no longer works.
+   It must be modified to explicitly import all subpackages,
+
+   i.e. ``import iris.cube; print(iris.cube.Cube)``.
 
 
 🔗 Dependencies
@@ -132,6 +152,7 @@ This document explains the changes made to Iris for this release
 
 #. `@pp-mo`_ removed dependency on `PyKE`_. (:pull:`4198`)
 
+.. _docs_section:
 
 📚 Documentation
 ================
@@ -223,6 +244,8 @@ This document explains the changes made to Iris for this release
    templates to remove an external URL reference that caused un-posted user issue
    content to be lost in the browser when followed. (:pull:`4147`)
 
+   .. _no_py36:
+
 #. `@bjlittle`_ dropped `Python 3.6`_ support, and automated the discovery of
    supported Python versions tested by `cirrus-ci`_ for documentation.
    (:pull:`4163`)

diff --git a/lib/iris/__init__.py b/lib/iris/__init__.py
@@ -103,7 +103,7 @@ def callback(cube, field, filename):
 
 
 # Iris revision.
-__version__ = "3.1.0rc0"
+__version__ = "3.1.0"
 
 # Restrict the names imported when using "from iris import *"
 __all__ = [

diff --git a/lib/iris/fileformats/abf.py b/lib/iris/fileformats/abf.py
@@ -10,7 +10,7 @@
 Including this module adds ABF and ABL loading to the session's capabilities.
 
 The documentation for this file format can be found
-`here <http://cliveg.bu.edu/modismisr/lai3g-fpar3g.html>`_.
+`here <https://nasanex.s3.amazonaws.com/AVHRR/GIMMS/LAI3G/00README_V01.pdf>`_.
 
 """
 

diff --git a/lib/iris/fileformats/netcdf.py b/lib/iris/fileformats/netcdf.py
@@ -6,7 +6,7 @@
 """
 Module to support the loading of a NetCDF file into an Iris cube.
 
-See also: `netCDF4 python <http://code.google.com/p/netcdf4-python/>`_.
+See also: `netCDF4 python <https://github.com/Unidata/netcdf4-python>`_
 
 Also refer to document 'NetCDF Climate and Forecast (CF) Metadata Conventions'.