test pull 2, please ignore

.travis.yml

@@ -5,53 +5,40 @@
 # we will use conda to give us a much faster setup time.
 
 
-language: python
-python:
-  - 2.7
-  - 3.6
-sudo: false
+language: minimal
+dist: xenial
 
 env:
-  matrix:
-    - TEST_TARGET=default TEST_MINIMAL=true
-    - TEST_TARGET=default
-    - TEST_TARGET=example
-    - TEST_TARGET=doctest
-
   global:
     # The decryption key for the encrypted .github/deploy_key.scitools-docs.enc.
     - secure: "N9/qBUT5CqfC7KQBDy5mIWZcGNuUJk3e/qmKJpotWYV+zwOI4GghJsRce6nFnlRiwl65l5oBEcvf3+sBvUfbZqh7U0MdHpw2tHhr2FSCmMB3bkvARZblh9M37f4da9G9VmRkqnyBM5G5TImXtoq4dusvNWKvLW0qETciaipq7ws="
+  matrix:
+    - PYTHON_VERSION=3.6 TEST_TARGET=default TEST_MINIMAL=true
+    - PYTHON_VERSION=3.6 TEST_TARGET=default
+    - PYTHON_VERSION=3.6 TEST_TARGET=example
+
+    - PYTHON_VERSION=3.7 TEST_TARGET=default TEST_MINIMAL=true
+    - PYTHON_VERSION=3.7 TEST_TARGET=default
+    - PYTHON_VERSION=3.7 TEST_TARGET=example
+    - PYTHON_VERSION=3.7 TEST_TARGET=doctest PUSH_BUILT_DOCS=true
 
 git:
   # We need a deep clone so that we can compute the age of the files using their git history.
   depth: 10000
 
 install:
   - >
-    export IRIS_TEST_DATA_REF="dba47566a9147645fea586f94a138e0a8d45a48e";
+    export IRIS_TEST_DATA_REF="1696ac3a823a06b95f430670f285ee97671d2cf2";
     export IRIS_TEST_DATA_SUFFIX=$(echo "${IRIS_TEST_DATA_REF}" | sed "s/^v//");
 
-  # Cut short doctest phase under Python 2 : now only supports Python 3
-  # SEE : https://github.com/SciTools/iris/pull/3134
-  # ------------
-  - >
-    if [[ $TEST_TARGET == 'doctest' && ${TRAVIS_PYTHON_VERSION} != 3* ]]; then
-        echo "DOCTEST phase only valid in Python 3 : ABORTING during 'install'."
-        exit 0
-    fi
-
   # Install miniconda
   # -----------------
   - >
     echo 'Installing miniconda';
-    export CONDA_BASE=https://repo.continuum.io/miniconda/Miniconda;
-    if [[ "$TRAVIS_PYTHON_VERSION" == 2* ]]; then
-      wget --quiet ${CONDA_BASE}2-latest-Linux-x86_64.sh -O miniconda.sh;
-    else
-      wget --quiet ${CONDA_BASE}3-latest-Linux-x86_64.sh -O miniconda.sh;
-    fi;
-    bash miniconda.sh -b -p $HOME/miniconda;
-    export PATH="$HOME/miniconda/bin:$PATH";
+    export CONDA_BASE="https://repo.continuum.io/miniconda/Miniconda";
+    wget --quiet ${CONDA_BASE}3-latest-Linux-x86_64.sh -O miniconda.sh;
+    bash miniconda.sh -b -p ${HOME}/miniconda;
+    export PATH="${HOME}/miniconda/bin:${PATH}";
 
   # Create the basic testing environment
   # ------------------------------------
@@ -63,35 +50,31 @@ install:
     conda config --add channels conda-forge;
     conda update --quiet conda;
     ENV_NAME='test-environment';
-    conda create --quiet -n $ENV_NAME python=$TRAVIS_PYTHON_VERSION pip;
-    source activate $ENV_NAME;
+    conda create --quiet -n ${ENV_NAME} python=${PYTHON_VERSION} pip;
+    source activate ${ENV_NAME};
 
   # Customise the testing environment
   # ---------------------------------
   - >
     echo 'Install Iris dependencies';
-    CONDA_REQS_FLAGS="";
     CONDA_REQS_GROUPS="test";
-    if [[ "$TRAVIS_PYTHON_VERSION" == 2* ]]; then
-        CONDA_REQS_FLAGS="${CONDA_REQS_FLAGS} --py2";
-    fi;
-    if [[ "$TEST_MINIMAL" != true ]]; then
+    if [[ "${TEST_MINIMAL}" != true ]]; then
         CONDA_REQS_GROUPS="${CONDA_REQS_GROUPS} all";
     fi;
     if [[ "${TEST_TARGET}" == 'doctest' ]]; then
         CONDA_REQS_GROUPS="${CONDA_REQS_GROUPS} docs";
     fi;
-    CONDA_REQS_FILE=conda-requirements.txt;
-    python requirements/gen_conda_requirements.py ${CONDA_REQS_FLAGS} --groups ${CONDA_REQS_GROUPS} > ${CONDA_REQS_FILE};
+    CONDA_REQS_FILE="conda-requirements.txt";
+    python requirements/gen_conda_requirements.py --groups ${CONDA_REQS_GROUPS} > ${CONDA_REQS_FILE};
     cat ${CONDA_REQS_FILE};
-    conda install --quiet -n $ENV_NAME --file ${CONDA_REQS_FILE};
+    conda install --quiet -n ${ENV_NAME} --file ${CONDA_REQS_FILE};
 
-  - PREFIX=$HOME/miniconda/envs/$ENV_NAME
+  - PREFIX="${HOME}/miniconda/envs/${ENV_NAME}"
 
   # Output debug info
   - >
-    conda list -n $ENV_NAME;
-    conda list -n $ENV_NAME --explicit;
+    conda list -n ${ENV_NAME};
+    conda list -n ${ENV_NAME} --explicit;
     conda info -a;
 
 # Pre-load Natural Earth data to avoid multiple, overlapping downloads.
@@ -100,71 +83,86 @@ install:
 
 # iris test data
   - >
-    if [[ "$TEST_MINIMAL" != true ]]; then
+    if [[ "${TEST_MINIMAL}" != true ]]; then
       wget --quiet -O iris-test-data.zip https://github.com/SciTools/iris-test-data/archive/${IRIS_TEST_DATA_REF}.zip;
       unzip -q iris-test-data.zip;
       mv "iris-test-data-${IRIS_TEST_DATA_SUFFIX}" iris-test-data;
     fi
 
 # set config paths
   - >
-    SITE_CFG=lib/iris/etc/site.cfg;
-    echo "[Resources]" > $SITE_CFG;
-    echo "test_data_dir = $(pwd)/iris-test-data/test_data" >> $SITE_CFG;
-    echo "doc_dir = $(pwd)/docs/iris" >> $SITE_CFG;
-    echo "[System]" >> $SITE_CFG;
-    echo "udunits2_path = $PREFIX/lib/libudunits2.so" >> $SITE_CFG;
+    SITE_CFG="lib/iris/etc/site.cfg";
+    echo "[Resources]" > ${SITE_CFG};
+    echo "test_data_dir = $(pwd)/iris-test-data/test_data" >> ${SITE_CFG};
+    echo "doc_dir = $(pwd)/docs/iris" >> ${SITE_CFG};
+    echo "[System]" >> ${SITE_CFG};
+    echo "udunits2_path = ${PREFIX}/lib/libudunits2.so" >> ${SITE_CFG};
 
   - python setup.py --quiet install
 
-  # JUST FOR NOW : Install latest version of iris-grib.
   # TODO : remove when iris doesn't do an integration test requiring iris-grib.
-  - if [[ "$TEST_MINIMAL" != true && ${TRAVIS_PYTHON_VERSION} == 2* ]]; then
-        conda install --quiet -n $ENV_NAME python-ecmwf_grib;
-        pip install git+https://github.com/SciTools/[email protected];
-    fi
+# TODO: uncomment and address the 5 failures and 10 errors in iris-grib.
+#  - if [[ "${TEST_MINIMAL}" != true ]]; then
+#        conda install --quiet -n ${ENV_NAME} python-eccodes;
+#        conda install --quiet -n ${ENV_NAME} --no-deps iris-grib;
+#    fi
 
 script:
   # Capture install-dir: As a test command must be last for get Travis to check
   # the RC, so it's best to start each operation with an absolute cd.
   - INSTALL_DIR=$(pwd)
 
   - >
-    if [[ $TEST_TARGET == 'default' ]]; then
-      export IRIS_REPO_DIR=$INSTALL_DIR;
-      python -m iris.tests.runner --default-tests --system-tests --print-failed-images --num-processors=3;
+    if [[ ${TEST_TARGET} == 'default' ]]; then
+      export IRIS_REPO_DIR=${INSTALL_DIR};
+      python -m iris.tests.runner --default-tests --system-tests --print-failed-images;
     fi
 
-  - if [[ $TEST_TARGET == 'example' ]]; then
-      python -m iris.tests.runner --example-tests --print-failed-images --num-processors=3;
+  - if [[ ${TEST_TARGET} == 'example' ]]; then
+      python -m iris.tests.runner --example-tests --print-failed-images;
     fi
 
+  # A call to check "whatsnew" contributions are valid, because the Iris test
+  # for it needs a *developer* install to be able to find the docs.
+  - if [[ ${TEST_TARGET} == 'doctest' ]]; then
+      cd ${INSTALL_DIR}/docs/iris/src/whatsnew;
+      python aggregate_directory.py --checkonly;
+    fi
+
+  # When pushing built docs, attempt to make a preliminary whatsnew by calling
+  # 'aggregate_directory.py', before the build.
   - >
-    if [[ $TEST_TARGET == 'doctest' ]]; then
-      MPL_RC_DIR=$HOME/.config/matplotlib;
-      mkdir -p $MPL_RC_DIR;
-      echo 'backend : agg' > $MPL_RC_DIR/matplotlibrc;
-      echo 'image.cmap : viridis' >> $MPL_RC_DIR/matplotlibrc;
-      cd $INSTALL_DIR/docs/iris;
+    if [[ ${PUSH_BUILT_DOCS} == 'true' ]]; then
+      cd ${INSTALL_DIR}/docs/iris/src/whatsnew;
+      WHATSNEW=$(ls -d contributions_* 2>/dev/null);
+      if [[ "$WHATSNEW" != "" ]]; then
+        python aggregate_directory.py --unreleased;
+      fi;
+    fi
+
+  # Build the docs.
+  - >
+    if [[ ${TEST_TARGET} == 'doctest' ]]; then
+      MPL_RC_DIR="${HOME}/.config/matplotlib";
+      mkdir -p ${MPL_RC_DIR};
+      echo 'backend : agg' > ${MPL_RC_DIR}/matplotlibrc;
+      echo 'image.cmap : viridis' >> ${MPL_RC_DIR}/matplotlibrc;
+      cd ${INSTALL_DIR}/docs/iris;
       make clean html && make doctest;
     fi
 
   # Split the organisation out of the slug. See https://stackoverflow.com/a/5257398/741316 for description.
   - ORG=(${TRAVIS_REPO_SLUG//\// })
 
-  # When we merge a change, and we are running in python 3, push some docs. 
-  - if [[ $TEST_TARGET == 'doctest' && ${TRAVIS_EVENT_TYPE} == 'push' && ${TRAVIS_PYTHON_VERSION} == 3* && ${ORG} == "SciTools" ]]; then
-      cd $INSTALL_DIR;
+  # When we merge a change to SciTools/iris, we can push docs to github pages.
+  # At present, only the Python 3.7 "doctest" job does this.
+  # Results appear at https://scitools-docs.github.io/iris/<<branchname>>/index.html
+  - if [[ ${ORG} == "SciTools" && ${TRAVIS_EVENT_TYPE} == 'push' && ${PUSH_BUILT_DOCS} == 'true' ]]; then
+      cd ${INSTALL_DIR};
       pip install doctr;
       doctr deploy --deploy-repo SciTools-docs/iris --built-docs docs/iris/build/html
         --key-path .github/deploy_key.scitools-docs.enc
         --no-require-master
         ${TRAVIS_BRANCH:-${TRAVIS_TAG}};
     fi
 
-  # An extra call to check "whatsnew" contributions are valid, because the
-  # Iris test for it needs a *developer* install to be able to find the docs.
-  - if [[ $TEST_TARGET == 'doctest' ]]; then
-      cd $INSTALL_DIR/docs/iris/src/whatsnew;
-      python aggregate_directory.py --checkonly;
-    fi

README.md

@@ -11,21 +11,27 @@
 
 <p align="center">
 <!-- https://shields.io/ is a good source of these -->
+<a href="https://travis-ci.org/SciTools/iris/branches">
+<img src="https://api.travis-ci.org/repositories/SciTools/iris.svg?branch=master"
+     alt="Travis-CI" /></a>
 <a href="https://anaconda.org/conda-forge/iris">
 <img src="https://img.shields.io/conda/dn/conda-forge/iris.svg"
      alt="conda-forge downloads" /></a>
+<a href="https://github.com/SciTools/iris/graphs/contributors">
+<img src="https://img.shields.io/github/contributors/SciTools/iris.svg"
+     alt="# contributors" /></a>
 <a href="https://github.com/SciTools/iris/releases">
 <img src="https://img.shields.io/github/tag/SciTools/iris.svg"
      alt="Latest version" /></a>
+<a href="https://scitools.org.uk/iris/docs/latest/index.html">
+<img src="https://img.shields.io/badge/docs-stable-green.svg"
+     alt="Stable docs" /></a>
 <a href="https://github.com/SciTools/iris/commits/master">
 <img src="https://img.shields.io/github/commits-since/SciTools/iris/latest.svg"
      alt="Commits since last release" /></a>
-<a href="https://github.com/SciTools/iris/graphs/contributors">
-<img src="https://img.shields.io/github/contributors/SciTools/iris.svg"
-     alt="# contributors" /></a>
-<a href="https://travis-ci.org/SciTools/iris/branches">
-<img src="https://api.travis-ci.org/repositories/SciTools/iris.svg?branch=master"
-     alt="Travis-CI" /></a>
+<a href="https://scitools-docs.github.io/iris/master/index.html">
+<img src="https://img.shields.io/badge/docs-latest-blue.svg"
+     alt="Latest docs" /></a>
 <a href="https://zenodo.org/badge/latestdoi/5312648">
 <img src="https://zenodo.org/badge/5312648.svg"
      alt="zenodo" /></a>
@@ -82,8 +88,10 @@ use of standard NumPy/dask arrays as its underlying data storage.
 
 # Documentation
 
-The documentation for Iris is available at <https://scitools.org.uk/iris/docs/latest>,
-including a user guide, example code, and gallery.
+<a href="https://scitools.org.uk/iris/docs/latest/index.html"> <img src="https://img.shields.io/badge/docs-stable-green.svg" alt="Stable docs" /></a> The documentation for *stable released versions* of Iris, including a user guide, example code, and gallery.
+
+<a href="https://scitools-docs.github.io/iris/master/index.html"> <img src="https://img.shields.io/badge/docs-latest-blue.svg" alt="Latest docs" /></a> The documentation for the *latest development version* of Iris.
+
 
 # Installation
 

docs/iris/example_code/Oceanography/load_nemo.py

@@ -0,0 +1,59 @@
+"""
+Load a time series of data from the NEMO model
+==============================================
+
+This example demonstrates how to load multiple files containing data output by
+the NEMO model and combine them into a time series in a single cube. The
+different time dimensions in these files can prevent Iris from concatenating
+them without the intervention shown here.
+"""
+from __future__ import unicode_literals
+
+import iris
+import iris.plot as iplt
+import iris.quickplot as qplt
+import matplotlib.pyplot as plt
+from iris.util import promote_aux_coord_to_dim_coord
+
+
+def main():
+    # Load the three files of sample NEMO data.
+    fname = iris.sample_data_path('NEMO/nemo_1m_*.nc')
+    cubes = iris.load(fname)
+
+    # Some attributes are unique to each file and must be blanked
+    # to allow concatenation.
+    differing_attrs = ['file_name', 'name', 'timeStamp', 'TimeStamp']
+    for cube in cubes:
+        for attribute in differing_attrs:
+            cube.attributes[attribute] = ''
+
+    # The cubes still cannot be concatenated because their time dimension is
+    # time_counter rather than time. time needs to be promoted to allow
+    # concatenation.
+    for cube in cubes:
+        promote_aux_coord_to_dim_coord(cube, 'time')
+
+    # The cubes can now be concatenated into a single time series.
+    cube = cubes.concatenate_cube()
+
+    # Generate a time series plot of a single point
+    plt.figure()
+    y_point_index = 100
+    x_point_index = 100
+    qplt.plot(cube[:, y_point_index, x_point_index], 'o-')
+
+    # Include the point's position in the plot's title
+    lat_point = cube.coord('latitude').points[y_point_index, x_point_index]
+    lat_string = '{:.3f}\u00B0 {}'.format(abs(lat_point),
+                                          'N' if lat_point > 0. else 'S')
+    lon_point = cube.coord('longitude').points[y_point_index, x_point_index]
+    lon_string = '{:.3f}\u00B0 {}'.format(abs(lon_point),
+                                          'E' if lon_point > 0. else 'W')
+    plt.title('{} at {} {}'.format(cube.long_name.capitalize(),
+                                   lat_string, lon_string))
+    iplt.show()
+
+
+if __name__ == '__main__':
+    main()

docs/iris/example_tests/test_load_nemo.py

@@ -0,0 +1,41 @@
+# (C) British Crown Copyright 2019, Met Office
+#
+# This file is part of Iris.
+#
+# Iris is free software: you can redistribute it and/or modify it under
+# the terms of the GNU Lesser General Public License as published by the
+# Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Iris is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with Iris.  If not, see <http://www.gnu.org/licenses/>.
+
+from __future__ import (absolute_import, division, print_function)
+from six.moves import (filter, input, map, range, zip)  # noqa
+
+# Import Iris tests first so that some things can be initialised before
+# importing anything else.
+import iris.tests as tests
+
+from .extest_util import (add_examples_to_path,
+                          show_replaced_by_check_graphic,
+                          fail_any_deprecation_warnings)
+
+
+class TestLoadNemo(tests.GraphicsTest):
+    """Test the load_nemo example code."""
+    def test_load_nemo(self):
+        with fail_any_deprecation_warnings():
+            with add_examples_to_path():
+                import load_nemo
+            with show_replaced_by_check_graphic(self):
+                load_nemo.main()
+
+
+if __name__ == '__main__':
+    tests.main()