Merge branch 'main' into votable_issues

* main:
  Use partial to make cube pickleable (SciTools#4377)
  Add edit via github method to Iris docs (SciTools#4461)
  Broken cartopy links in docs (SciTools#4464)
  rtd with latest mambaforge image for faster building (SciTools#4476)
  Show acceptable image test results in the docs (SciTools#4392)
  Nc load latlon fix (SciTools#4470)
  update matplotlib links (SciTools#4474)
  Whatsnew for PR 4462 (SciTools#4475)
  Clarify the return type of iris.load (AVD-1899) (SciTools#4462)
  [pre-commit.ci] pre-commit autoupdate (SciTools#4472)
  Updated environment lockfiles (SciTools#4467)

.pre-commit-config.yaml

@@ -13,7 +13,7 @@ minimum_pre_commit_version: 1.21.0
 
 repos:
 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.0.1
+    rev: v4.1.0
     hooks:
         # Prevent giant files from being committed.
     -   id: check-added-large-files

.readthedocs.yml

@@ -1,20 +1,20 @@
 version: 2
 
 build:
-    image: latest
+  os: ubuntu-20.04
+  tools:
+    python: mambaforge-4.10
 
 conda:
-    environment: requirements/ci/readthedocs.yml
+  environment: requirements/ci/readthedocs.yml
 
 sphinx:
-    configuration: docs/src/conf.py
-    fail_on_warning: false
+  configuration: docs/src/conf.py
+  fail_on_warning: false
 
 python:
-    install: 
-        - method: setuptools
-          path: .
-
-formats:
-    - htmlzip
-    - pdf
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

docs/gallery_code/README.rst

@@ -23,4 +23,4 @@ you may start the jupyter notebook via::
 
 If you wish to contribute to the gallery see the 
 :ref:`contributing.documentation.gallery` section of the 
-:ref:`contributing.documentation`.
+:ref:`contributing.documentation_full`.

docs/src/_templates/imagehash.html

@@ -0,0 +1,15 @@
+{% extends "!layout.html" %}
+
+{% block body %}
+
+<h1>Test: {{ test }}</h1>
+
+
+{% for hash, file in hashfiles %}
+<div>
+    <h3>{{hash}}</h3>
+    <img src="{{file}}" />
+</div>
+{% endfor %}
+
+{% endblock %}

docs/src/conf.py

@@ -158,6 +158,7 @@ def _dotv(version):
     "sphinx_gallery.gen_gallery",
     "matplotlib.sphinxext.mathmpl",
     "matplotlib.sphinxext.plot_directive",
+    "image_test_output",
 ]
 
 if skip_api == "1":

docs/src/developers_guide/contributing_documentation.rst

@@ -1,173 +1,21 @@
 
-.. _contributing.documentation:
-
-Contributing to the Documentation
----------------------------------
+How to Contribute to the Documentation
+--------------------------------------
 
 Documentation is important and we encourage any improvements that can be made.
 If you believe the documentation is not clear please contribute a change to
 improve the documentation for all users.
 
-Any change to the Iris project whether it is a bugfix, new feature or
-documentation update must use the :ref:`development-workflow`.
-
-
-Requirements
-~~~~~~~~~~~~
-
-The documentation uses specific packages that need to be present.  Please see
-:ref:`installing_iris` for instructions.
-
-
-.. _contributing.documentation.building:
-
-Building
-~~~~~~~~
-
-This documentation was built using the latest Python version that Iris
-supports.  For more information see :ref:`installing_iris`.
-
-The build can be run from the documentation directory ``docs/src``.
-
-The build output for the html is found in the ``_build/html`` sub directory.
-When updating the documentation ensure the html build has *no errors* or
-*warnings* otherwise it may fail the automated `cirrus-ci`_  build.
-
-Once the build is complete, if it is rerun it will only rebuild the impacted
-build artefacts so should take less time.
-
-There is an option to perform a build but skip the
-:ref:`contributing.documentation.gallery` creation completely.  This can be
-achieved via::
-
-    make html-noplot
-
-Another option is to skip the :ref:`iris` documentation creation.  This can be
-useful as it reduces the time to build the documentation, however you may have
-some build warnings as there maybe references to the API documentation.
-This can be achieved via::
-
-    make html-noapi
-
-You can combine both the above and skip the
-:ref:`contributing.documentation.gallery` and :ref:`iris` documentation
-completely.  This can be achieved via::
-
-    make html-quick
-
-If you wish to run a full clean build you can run::
-
-    make clean
-    make html
-
-This is useful for a final test before committing your changes.
-
-.. note:: In order to preserve a clean build for the html, all **warnings**
-          have been promoted to be **errors** to ensure they are addressed.
-          This **only** applies when ``make html`` is run.
-
-.. _cirrus-ci: https://cirrus-ci.com/github/SciTools/iris
-
-.. _contributing.documentation.testing:
-
-Testing
-~~~~~~~
-
-There are a ways to test various aspects of the documentation.  The
-``make`` commands shown below can be run in the ``docs`` or
-``docs/src`` directory.
-
-Each :ref:`contributing.documentation.gallery` entry has a corresponding test.
-To run the tests::
-
-    make gallerytest
-
-Many documentation pages includes python code itself that can be run to ensure
-it is still valid or to demonstrate examples.  To ensure these tests pass
-run::
-
-    make doctest
-
-See :data:`iris.cube.Cube.data` for an example of using the `doctest`_
-approach.
-
-.. _doctest: http://www.sphinx-doc.org/en/stable/ext/doctest.html
-
-The hyperlinks in the documentation can be checked automatically.
-If there is a link that is known to work it can be excluded from the checks by
-adding it to the ``linkcheck_ignore`` array that is defined in the
-`conf.py`_.  The hyperlink check can be run via::
-
-    make linkcheck
-
-If this fails check the output for the text **broken** and then correct
-or ignore the url.
-
-.. comment
-    Finally, the spelling in the documentation can be checked automatically via the
-    command::
-
-        make spelling
-
-    The spelling check may pull up many technical abbreviations and acronyms.  This
-    can be managed by using an **allow** list in the form of a file.  This file,
-    or list of files is set in the `conf.py`_ using the string list
-    ``spelling_word_list_filename``.
-
-
-.. note:: In addition to the automated `cirrus-ci`_ build of all the
-          documentation build options above, the
-          https://readthedocs.org/ service is also used.  The configuration
-          of this held in a file in the root of the
-          `github Iris project <https://github.com/SciTools/iris>`_  named
-          ``.readthedocs.yml``.
-
-
-.. _conf.py: https://github.com/SciTools/iris/blob/main/docs/src/conf.py
-
-
-.. _contributing.documentation.api:
-
-Generating API Documentation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-In order to auto generate the API documentation based upon the docstrings a
-custom set of python scripts are used, these are located in the directory
-``docs/src/sphinxext``.  Once the ``make html`` command has been run,
-the output of these scripts can be found in
-``docs/src/generated/api``.
-
-If there is a particularly troublesome module that breaks the ``make html`` you
-can exclude the module from the API documentation.  Add the entry to the
-``exclude_modules`` tuple list in the
-``docs/src/sphinxext/generate_package_rst.py`` file.
-
-
-.. _contributing.documentation.gallery:
-
-Gallery
-~~~~~~~
-
-The Iris :ref:`sphx_glr_generated_gallery` uses a sphinx extension named
-`sphinx-gallery <https://sphinx-gallery.github.io/stable/>`_
-that auto generates reStructuredText (rst) files based upon a gallery source
-directory that abides directory and filename convention.
-
-The code for the gallery entries are in ``docs/gallery_code``.
-Each sub directory in this directory is a sub section of the gallery.  The
-respective ``README.rst`` in each folder is included in the gallery output.
-
-For each gallery entry there must be a corresponding test script located in
-``docs/gallery_tests``.
+If you're confident diving right in, please head for
+:ref:`contributing.documentation_full`.
 
-To add an entry to the gallery simple place your python code into the
-appropriate sub directory and name it with a prefix of ``plot_``.  If your
-gallery entry does not fit into any existing sub directories then create a new
-directory and place it in there.
+If you're not then we've got a step-by-step guide here to walk you through it:
+:ref:`contributing.documentation_easy`
 
-The reStructuredText (rst) output of the gallery is located in
-``docs/src/generated/gallery``.
+.. toctree::
+   :maxdepth: 1
+   :hidden:
 
-For more information on the directory structure and options please see the
-`sphinx-gallery getting started
-<https://sphinx-gallery.github.io/stable/getting_started.html>`_ documentation.
+   contributing_documentation_easy
+   contributing_documentation_full
+   

docs/src/developers_guide/contributing_documentation_easy.rst

@@ -0,0 +1,102 @@
+
+.. _contributing.documentation_easy:
+
+Contributing to the Documentation (the easy way)
+------------------------------------------------
+
+Documentation is important and we encourage any improvements that can be made.
+If you believe the documentation is not clear please contribute a change to
+improve the documentation for all users.
+
+The guide below is designed to be accessible to those with little-to-no
+knowledge of programming and GitHub. If you find that something doesn't work as
+described or could use more explanation then please let us know (or contribute
+the improvement yourself)!
+
+First Time Only Steps
+^^^^^^^^^^^^^^^^^^^^^
+
+1. Create a `GitHub <https://github.com/>`_ account.
+
+2. Complete the Scitools Contributor License Agreement (`link to Google Form
+   <https://docs.google.com/forms/d/e/1FAIpQLSfd0tdE-DcJOXh8ej_7T93IizwJFYBFyRWYQOi2A8QRaKwykA/viewform>`_).
+   This is a one-off requirement for anyone who wishes to contribute to a
+   Scitools repository - including the documentation.
+
+Steps to Complete Each Time You Propose Changes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. Navigate to the documentation page that you want to edit (on this site).
+
+2. Click the ``Edit on GitHub`` button at the **top right** of the page.
+
+.. image:: edit_on_github.png
+
+3. In the resulting GitHub page select **main** from the ``Switch
+   branches/tags`` drop-down menu near the **top left** of the page (to the left
+   of the ``iris / docs / src / ...`` links) if it isn't already. This changes
+   the branch to **main**.
+
+.. image:: find_main.png
+
+4. Click the pencil symbol near the **top right** (to the right of the ``Raw``
+   and ``Blame`` buttons).
+
+.. image:: edit_button.png
+
+5. Make your edits! Try to strike a balance between informing the audience
+   enough that they understand and overwhelming them with information.
+
+.. note::
+
+    You may see the following message at the top of the edit page, informing you
+    that GitHub has created you your own ``fork`` (or copy) of the project as a
+    precursor to allowing you to edit the page. Your changes will be merged into
+    the main version of the documentation later.
+
+    .. image:: fork_banner.png
+
+6. Scroll to the bottom of the edit page and enter some appropriate information
+   in the two boxes under ``Propose changes``. You can just keep the default text
+   if you like or enter something more specific - a short sentence explaining
+   what's changed is fine. Then click the ``Propose changes`` button.
+
+.. image:: propose_changes.png
+
+7. In the resulting page titled ``Pull Request``, write a brief description of
+   what you've changed underneath the following three lines:
+
+.. code::
+
+    ### Description
+    <!-- Provide a clear description about your awesome pull request -->
+    <!-- Tell us all about your new feature, improvement, or bug fix -->
+
+Describing what you've changed and why will help the person who reviews your changes.
+
+.. image:: pull_request.png
+
+8.	Click the ``Create pull request`` button.
+
+.. tip::
+
+   If you're not sure that you're making your pull request right, or have a
+   question, then make it anyway! You can then comment on it tagging
+   ``@SciTools/iris-devs`` to ask your question (then edit your pull request if
+   you need to).
+
+What Happens Next?
+^^^^^^^^^^^^^^^^^^
+
+Another Iris contributor will review your changes (this happens for everyone who
+makes changes to Iris or its documentation). The reviewer might make comments or
+ask questions (don't worry about missing these, GitHub will email you to let you
+know). You can respond to these comments underneath where they appear in GitHub.
+
+Once you've worked everything out together, the reviewer will merge your changes
+into the main version of the documentation so that they're accessible for
+everyone to benefit from.
+
+**You've now contributed to the Iris documentation!** If you've caught the bug
+and want to get more involved (or you're just interested what that would mean)
+then chat to the person reviewing your code or another Iris contributor.