Read The Docs documentation

.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,19 @@
+version: 2
+
+build:
+    image: latest
+
+conda:
+    environment: ci/requirements/readthedocs-conda.yml
+
+sphinx:
+    configuration: docs/iris/src/conf.py
+    fail_on_warning: false
+
+python:
+    install: 
+        - method: setuptools
+          path: .
+
+formats:
+    - htmlzip

.travis.yml

@@ -15,12 +15,12 @@ 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
 
 git:
   # We need a deep clone so that we can compute the age of the files using their git history.
@@ -61,8 +61,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};
@@ -118,8 +118,8 @@ script:
       python -m iris.tests.runner --default-tests --system-tests;
     fi
 
-  - if [[ "${TEST_TARGET}" == 'example' ]]; then
-      python -m iris.tests.runner --example-tests;
+  - if [[ "${TEST_TARGET}" == 'gallery' ]]; then
+      python -m iris.tests.runner --gallery-tests;
     fi
 
   # A call to check "whatsnew" contributions are valid, because the Iris test
@@ -152,6 +152,17 @@ 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
+
   # 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 (?!)

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

ci/requirements/readthedocs-conda.yml

@@ -0,0 +1,60 @@
+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==1.1.3
+  - dask>=2
+  - matplotlib
+  - netcdf4
+  - numpy>=1.14
+  - scipy
+
+# 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

@@ -20,28 +20,36 @@ pdf:
 
 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 . 

docs/iris/gallery_code/README.rst

@@ -0,0 +1,26 @@
+Gallery
+=======
+
+The gallery is divided into sections as described below.  All entries
+show the code used to produce the example plot.  Additionally there are links
+to download the code directly as source or as part of a 
+`jupyter notebook <https://jupyterlab.readthedocs.io/en/stable/>`_, 
+these links are at the bottom of the page.
+
+In order to successfuly view the jupyter notebook locally so you may
+experiment with the code you will need an environment setup with the 
+appropriate dependencies, see :ref:`installing_iris` for instructions.  
+Ensure that ``iris-sample-data`` is installed as it is used in the gallery.  
+Additionally ensure that you install ``jupyter``.  The command to install both
+is::
+
+    conda install -c conda-forge iris-sample-data jupyter
+
+Once you have downloaded the notebooks (bottom of each gallery page), 
+you may start the jupyter notebook via::
+
+  jupyter notebook
+
+If you wish to contribute to the gallery see the 
+:ref:`contributing.documentation.gallery` section of the 
+:ref:`contributing.documentation`.

docs/iris/gallery_code/general/README.rst

@@ -0,0 +1,2 @@
+General
+-------

docs/iris/example_code/General/anomaly_log_colouring.py → docs/iris/gallery_code/general/plot_anomaly_log_colouring.py

@@ -13,7 +13,7 @@
 
 To do this, we create a custom value mapping function (normalization) using
 the matplotlib Norm class `matplotlib.colours.SymLogNorm
-<http://matplotlib.org/api/colors_api.html#matplotlib.colors.SymLogNorm>`_.
+<https://matplotlib.org/api/_as_gen/matplotlib.colors.SymLogNorm.html#matplotlib.colors.SymLogNorm>`_.
 We use this to make a cell-filled pseudocolour plot with a colorbar.
 
 NOTE: By "pseudocolour", we mean that each data point is drawn as a "cell"

docs/iris/gallery_code/meteorology/README.rst

@@ -0,0 +1,3 @@
+Meteorology
+-----------
+

docs/iris/gallery_code/oceanography/README.rst

@@ -0,0 +1,3 @@
+Oceanography
+------------
+

docs/iris/example_tests/extest_util.py → docs/iris/gallery_tests/gallerytest_util.py

@@ -6,7 +6,7 @@
 
 """
 Provides context managers which are fundamental to the ability
-to run the example tests.
+to run the gallery tests.
 
 """
 
@@ -23,26 +23,26 @@
 import iris.quickplot as qplt
 
 
-EXAMPLE_DIRECTORY = os.path.join(
-    os.path.dirname(os.path.dirname(__file__)), "example_code"
+GALLERY_DIRECTORY = os.path.join(
+    os.path.dirname(os.path.dirname(__file__)), "gallery_code"
 )
-EXAMPLE_DIRECTORIES = [
-    os.path.join(EXAMPLE_DIRECTORY, the_dir)
-    for the_dir in os.listdir(EXAMPLE_DIRECTORY)
+GALLERY_DIRECTORIES = [
+    os.path.join(GALLERY_DIRECTORY, the_dir)
+    for the_dir in os.listdir(GALLERY_DIRECTORY)
 ]
 
 
 @contextlib.contextmanager
-def add_examples_to_path():
+def add_gallery_to_path():
     """
-    Creates a context manager which can be used to add the iris examples
-    to the PYTHONPATH. The examples are only importable throughout the lifetime
+    Creates a context manager which can be used to add the iris gallery 
+    to the PYTHONPATH. The gallery entries are only importable throughout the lifetime
     of this context manager.
 
     """
     orig_sys_path = sys.path
     sys.path = sys.path[:]
-    sys.path += EXAMPLE_DIRECTORIES
+    sys.path += GALLERY_DIRECTORIES
     yield
     sys.path = orig_sys_path
 

docs/iris/example_tests/test_COP_1d_plot.py → docs/iris/gallery_tests/test_plot_COP_1d.py

@@ -8,22 +8,22 @@
 # importing anything else.
 import iris.tests as tests
 
-from .extest_util import (
-    add_examples_to_path,
+from .gallerytest_util import (
+    add_gallery_to_path,
     show_replaced_by_check_graphic,
     fail_any_deprecation_warnings,
 )
 
 
 class TestCOP1DPlot(tests.GraphicsTest):
-    """Test the COP_1d_plot example code."""
+    """Test the COP_1d_plot gallery code."""
 
-    def test_COP_1d_plot(self):
+    def test_plot_COP_1d(self):
         with fail_any_deprecation_warnings():
-            with add_examples_to_path():
-                import COP_1d_plot
+            with add_gallery_to_path():
+                import plot_COP_1d
             with show_replaced_by_check_graphic(self):
-                COP_1d_plot.main()
+                plot_COP_1d.main()
 
 
 if __name__ == "__main__":

docs/iris/example_tests/test_COP_maps.py → docs/iris/gallery_tests/test_plot_COP_maps.py

@@ -8,22 +8,22 @@
 # importing anything else.
 import iris.tests as tests
 
-from .extest_util import (
-    add_examples_to_path,
+from .gallerytest_util import (
+    add_gallery_to_path,
     show_replaced_by_check_graphic,
     fail_any_deprecation_warnings,
 )
 
 
 class TestCOPMaps(tests.GraphicsTest):
-    """Test the COP_maps example code."""
+    """Test the COP_maps gallery code."""
 
-    def test_cop_maps(self):
+    def test_plot_cop_maps(self):
         with fail_any_deprecation_warnings():
-            with add_examples_to_path():
-                import COP_maps
+            with add_gallery_to_path():
+                import plot_COP_maps
             with show_replaced_by_check_graphic(self):
-                COP_maps.main()
+                plot_COP_maps.main()
 
 
 if __name__ == "__main__":