Merge "default_units" feature branch (to master)

.flake8

@@ -15,6 +15,8 @@ ignore =
     E402,
     # E501: line too long
     E501,
+    # E731: do not assign a lambda expression, use a def
+    E731,
     # W503: line break before binary operator
     W503,
     # W504: line break after binary operator
@@ -26,8 +28,8 @@ exclude =
     .eggs,
     build,
     compiled_krb,
-    sphinxext,
-    tools,
+    docs/iris/src/sphinxext/*,
+    tools/*,
     #
     # ignore auto-generated files
     #
@@ -38,3 +40,7 @@ exclude =
     # ignore third-party files
     #
     gitwash_dumper.py,
+    #
+    # convenience imports
+    #
+    lib/iris/common/__init__.py

.gitignore

@@ -55,11 +55,8 @@ lib/iris/tests/results/imagerepo.lock
 *.cover
 
 # Auto generated documentation files
-docs/iris/src/_static/random_image.js
-docs/iris/src/_templates/gallery.html
-docs/iris/src/examples/
-docs/iris/src/iris/
-docs/iris/src/matplotlibrc
+docs/iris/src/_build/*
+docs/iris/src/generated
 
 # Example test results
 docs/iris/iris_image_test_output/

.readthedocs.yml

@@ -0,0 +1,20 @@
+version: 2
+
+build:
+    image: latest
+
+conda:
+    environment: ci/requirements/readthedocs.yml
+
+sphinx:
+    configuration: docs/iris/src/conf.py
+    fail_on_warning: false
+
+python:
+    install: 
+        - method: setuptools
+          path: .
+
+formats:
+    - htmlzip
+    - pdf

.travis.yml

@@ -15,12 +15,15 @@ env:
   matrix:
     - PYTHON_VERSION=3.6 TEST_TARGET=default TEST_MINIMAL=true
     - PYTHON_VERSION=3.6 TEST_TARGET=default TEST_BLACK=true
-    - PYTHON_VERSION=3.6 TEST_TARGET=example
-
+    - PYTHON_VERSION=3.6 TEST_TARGET=gallery
     - PYTHON_VERSION=3.7 TEST_TARGET=default TEST_MINIMAL=true
     - PYTHON_VERSION=3.7 TEST_TARGET=default TEST_BLACK=true
-    - PYTHON_VERSION=3.7 TEST_TARGET=example
+    - PYTHON_VERSION=3.7 TEST_TARGET=gallery
     - PYTHON_VERSION=3.7 TEST_TARGET=doctest PUSH_BUILT_DOCS=true
+    - PYTHON_VERSION=3.7 TEST_TARGET=linkcheck
+    # TODO: Dependencies for sphinxcontrib-spelling to be in place before this
+    #       spelling code block is enabled
+    #- PYTHON_VERSION=3.7 TEST_TARGET=spelling
 
 git:
   # We need a deep clone so that we can compute the age of the files using their git history.
@@ -61,8 +64,8 @@ install:
     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";
+    if [[ "${TEST_TARGET}" == 'doctest' || "${TEST_TARGET}" == 'linkcheck' ]]; then
+            CONDA_REQS_GROUPS="${CONDA_REQS_GROUPS} docs";
     fi;
     CONDA_REQS_FILE="conda-requirements.txt";
     python requirements/gen_conda_requirements.py --groups ${CONDA_REQS_GROUPS} > ${CONDA_REQS_FILE};
@@ -100,15 +103,6 @@ install:
 
   - python setup.py --quiet install
 
-  # TODO : remove when iris doesn't do an integration test requiring iris-grib.
-  # test against the latest version of python-eccodes.
-  # Conda-forge versioning is out of order (0.9.* is later than 2.12.*).
-  - >
-    if [[ "${TEST_MINIMAL}" != true ]]; then
-        conda install --quiet -n ${ENV_NAME} python-eccodes">=0.9.1, <2";
-        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.
@@ -127,27 +121,9 @@ script:
       python -m iris.tests.runner --default-tests --system-tests;
     fi
 
-  - if [[ "${TEST_TARGET}" == 'example' ]]; then
-      python -m iris.tests.runner --example-tests;
-    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 [[ "${PUSH_BUILT_DOCS}" == 'true' ]]; then
-      cd ${INSTALL_DIR}/docs/iris/src/whatsnew;
-      WHATSNEW=$(ls -d contributions_* 2>/dev/null);
-      if [[ -n "${WHATSNEW}" ]]; then
-        python aggregate_directory.py --unreleased;
-      fi;
+   if [[ "${TEST_TARGET}" == 'gallery' ]]; then
+      python -m iris.tests.runner --gallery-tests;
     fi
 
   # Build the docs.
@@ -161,6 +137,31 @@ script:
       make clean html && make doctest;
     fi
 
+  # check the links in the docs
+  - >
+    if [[ "${TEST_TARGET}" == 'linkcheck' ]]; 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 && make linkcheck;
+    fi
+
+  # TODO: Dependencies for sphinxcontrib-spelling to be in place before this
+  #       spelling code block is enabled
+
+  # check the spelling in the docs
+  # - >
+  #   if [[ "${TEST_TARGET}" == 'spelling' ]]; 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 && make spelling;
+  #   fi
+
   # Split the organisation out of the slug. See https://stackoverflow.com/a/5257398/741316 for description.
   # NOTE: a *separate* "export" command appears to be necessary here : A command of the
   #   form "export ORG=.." failed to define ORG for the following command (?!)
@@ -176,7 +177,7 @@ script:
   - 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
+      doctr deploy --deploy-repo SciTools-docs/iris --built-docs docs/iris/src/_build/html
         --key-path .github/deploy_key.scitools-docs.enc
         --no-require-master
         ${TRAVIS_BRANCH:-${TRAVIS_TAG}};

INSTALL

@@ -1,9 +1,11 @@
 You can either install Iris using the conda package manager or from source.
 
+
 Installing using conda
 ----------------------
 
 Iris is available using conda for the following platforms:
+
  * Linux 64-bit,
  * Mac OSX 64-bit, and
  * Windows 32-bit and 64-bit.
@@ -16,8 +18,7 @@ the following command::
 
   conda install -c conda-forge iris
 
-If you wish to run any of the code examples
-(see http://scitools.org.uk/iris/docs/latest/examples/index.html) you will also
+If you wish to run any of the code in the gallery you will also
 need the Iris sample data. This can also be installed using conda::
 
   conda install -c conda-forge iris-sample-data
@@ -77,7 +78,7 @@ Hence the commands change to::
     conda activate my_iris_env  # or whatever other name you gave it
     pip install -e .
 
-The tests can then be run with
+The tests can then be run with::
 
     python setup.py test
 

README.md

@@ -1,9 +1,9 @@
 <h1 align="center">
-  <a href="https://scitools.org.uk/iris/docs/latest/" style="display: block; margin: 0 auto;">
-   <img src="docs/iris/src/_static/logo_banner.png"
-        style="max-width: 40%;" alt="Iris"></a><br>
+  <a href="https://scitools.org.uk/iris/docs/latest/">
+   <img src="docs/iris/src/_static/iris-logo-title.png" alt="Iris" width="300"></a><br>
 </h1>
 
+
 <h4 align="center">
     Iris is a powerful, format-agnostic, community-driven Python library for
     analysing and visualising Earth science data
@@ -14,6 +14,9 @@
 <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-iris.readthedocs.io/en/latest/?badge=latest'>
+    <img src='https://readthedocs.org/projects/scitools-iris/badge/?version=latest' 
+    alt='Documentation Status' /></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>
@@ -29,9 +32,6 @@
 <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://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>
@@ -120,4 +120,4 @@ of its [GNU LGPLv3 license](COPYING.LESSER).
 # Contributing
 Information on how to contribute can be found in the [Iris developer guide](https://scitools.org.uk/iris/docs/latest/developers_guide/index.html).
 
-(C) British Crown Copyright 2010 - 2019, Met Office
+(C) British Crown Copyright 2010 - 2020, Met Office

ci/requirements/readthedocs.yml

@@ -0,0 +1,61 @@
+name: iris-docs
+
+channels:
+  - conda-forge
+
+dependencies:
+# Dependencies necessary to run setup.py of iris
+# ----------------------------------------------
+  - setuptools
+  - pyke
+
+# Absolute minimal dependencies for iris
+# --------------------------------------
+
+# Without these, iris won't even import.
+
+  - cartopy>=0.12
+  - proj4<6
+  - cf-units>=2
+  - cftime
+  - dask>=2
+  - matplotlib<3.3
+  - netcdf4
+  - numpy>=1.14
+  - scipy
+  - python-xxhash
+
+# Dependencies needed to run the iris tests
+#------------------------------------------
+
+  - black=19.10b0
+  - filelock
+  - pillow<7
+  - imagehash>=4.0
+  - nose
+  - pre-commit
+  - requests
+  - asv
+
+# Dependencies for a feature complete installation
+# ------------------------------------------------
+
+# esmpy regridding not available through pip.
+  - esmpy>=7.0
+#gdal : under review -- not tested at present
+  - mo_pack
+  - nc-time-axis
+  - pandas
+  - python-stratify
+  - pyugrid
+
+  - graphviz
+
+# Iris sample data is not available through pip. It can be installed from
+# https://github.com/SciTools/iris-sample-data/archive/master.zip
+  - iris-sample-data
+  - sphinx
+  - sphinx_rtd_theme  
+  - sphinx-copybutton
+  - sphinx-gallery
+

docs/iris/Makefile

@@ -5,43 +5,48 @@ html:
         echo "make html in $$i..."; \
         (cd $$i; $(MAKE) $(MFLAGS) $(MYMAKEFLAGS) html); done
 
-pdf:
-	@for i in $(SUBDIRS); do\
-	echo "make latex in $$i.."; \
-	(cd $$i; $(MAKE) $(MFLAGS) $(MYMAKEFLAGS) latex); done
-	echo "\def\sphinxdocclass{MO_report}" > build/latex/docs.tex
-	echo "\documentclass[letterpaper,10pt,english]{MO_report}" >> build/latex/docs.tex
-	tail -n +4 build/latex/Iris.tex >> build/latex/docs.tex
-	sed 's/\\tableofcontents/\\tableofcontents\n\\pagenumbering\{arabic\}/' build/latex/docs.tex > build/latex/docs2.tex
-	sed 's/subsection{/section{/' build/latex/docs2.tex > build/latex/documentation.tex
-	(cd build/latex; pdflatex -interaction=scrollmode documentation.tex)
-	# call latex again to get page numbers right...
-	(cd build/latex; pdflatex -interaction=scrollmode documentation.tex);
+html-noplot:
+	@for i in $(SUBDIRS); do \
+        echo "make html-noplot in $$i..."; \
+        (cd $$i; $(MAKE) $(MFLAGS) $(MYMAKEFLAGS) html-noplot); done
+
+spelling:
+	@for i in $(SUBDIRS); do \
+        echo "make spelling in $$i..."; \
+        (cd $$i; $(MAKE) $(MFLAGS) $(MYMAKEFLAGS) spelling); done
 
 all:
 	@for i in $(SUBDIRS); do \
-	echo "make all in $$i..."; \
-	(cd $$i; $(MAKE) $(MFLAGS) $(MYMAKEFLAGS) all); done
+		echo "make all in $$i..."; \
+		(cd $$i; $(MAKE) $(MFLAGS) $(MYMAKEFLAGS) all); done
+
 install:
 	@for i in $(SUBDIRS); do \
-	echo "Installing in $$i..."; \
-	(cd $$i; $(MAKE) $(MFLAGS) $(MYMAKEFLAGS) install); done
+		echo "Installing in $$i..."; \
+		(cd $$i; $(MAKE) $(MFLAGS) $(MYMAKEFLAGS) install); done
+
 build:
 	@for i in $(SUBDIRS); do \
-	echo "Clearing in $$i..."; \
-	(cd $$i; $(MAKE) $(MFLAGS) $(MYMAKEFLAGS) build); done
+		echo "Clearing in $$i..."; \
+		(cd $$i; $(MAKE) $(MFLAGS) $(MYMAKEFLAGS) build); done
+
 clean:
 	@for i in $(SUBDIRS); do \
-	echo "Clearing in $$i..."; \
-	(cd $$i; $(MAKE) $(MFLAGS) $(MYMAKEFLAGS) clean); done
+		echo "Clearing in $$i..."; \
+		(cd $$i; $(MAKE) $(MFLAGS) $(MYMAKEFLAGS) clean); done
 
 doctest:
 	@for i in $(SUBDIRS); do \
         echo "Running doctest in $$i..."; \
         (cd $$i; $(MAKE) $(MFLAGS) $(MYMAKEFLAGS) doctest); done
 
-extest:
+linkcheck:
+	@for i in $(SUBDIRS); do \
+		echo "Running linkcheck in $$i..."; \
+		(cd $$i; $(MAKE) $(MFLAGS) $(MYMAKEFLAGS) linkcheck); done
+
+gallerytest:
 	@echo
-	@echo "Running \"example_code/graphics\" tests..."
+	@echo "Running \"gallery\" tests..."
 	@echo
 	python -m unittest discover -v -t .