Merge branch 'master' into contribution_overhaul

* master:
  Fix sphinx logger (SciTools#3832)
  whatsnew entry for dependencies (SciTools#3831)
  Added link to scitools.org.uk on the main index. (SciTools#3830)

docs/iris/src/index.rst

@@ -43,6 +43,8 @@ single-machine workflows right through to multi-core clusters and HPC.
 Interoperability with packages from the wider scientific Python ecosystem comes
 from Iris' use of standard NumPy/dask arrays as its underlying data storage.
 
+Iris is part of SciTools, for more information see https://scitools.org.uk/.
+
 
 .. toctree::
    :maxdepth: 1

docs/iris/src/userguide/regridding_plots/regridding_plot.py

@@ -22,6 +22,4 @@
 ax.coastlines(resolution="50m")
 ax.gridlines()
 
-plt.tight_layout()
-
 plt.show()

docs/iris/src/whatsnew/latest.rst

@@ -24,8 +24,8 @@ Features
   associated with an axis over which the statistic is being run.
 
 * Supporting ``Iris`` for both ``Python2`` and ``Python3`` resulted in pinning our
-  dependency on `matplotlib`_ at ``v2.x``.  Now that ``Python2`` support has
-  been dropped, ``Iris`` is free to use the latest version of `matplotlib`_.
+  dependency on `Matplotlib`_ at ``v2.x``.  Now that ``Python2`` support has
+  been dropped, ``Iris`` is free to use the latest version of `Matplotlib`_.
 
 * `CF Ancillary Data`_ variables are now supported, and can be loaded from and
   saved to NetCDF-CF files. Support for `Quality Flags`_ is also provided to
@@ -35,16 +35,17 @@ Features
 Dependency Updates
 ==================
 
-* Iris now supports the latest version of
-  `Proj <https://github.com/OSGeo/PROJ>`_.
+* Iris now supports the latest version of `Proj <https://github.com/OSGeo/PROJ>`_.
 
 * Iris now requires `Cartopy <https://github.com/SciTools/cartopy>`_ >= 0.18 in
-  order to remain compatible with the latest version of
-  `Matplotlib <https://github.com/matplotlib/matplotlib>`_.
+  order to remain compatible with the latest version of `Matplotlib`_.
 
 * GDAL is removed from the extensions dependency group. We no longer consider it to
   be an extension.
 
+* Configuring Iris and :ref:`installing_from_source` as a developer, with all the
+  required package dependencies is now easier with our curated conda environment
+  YAML files. See :pull:`3812`.
 
 Bugs Fixed
 ==========
@@ -125,10 +126,13 @@ Internal
 ========
 
 * Changed the numerical values in tests involving the Robinson projection due
-  to improvements made in `Proj <https://github.com/OSGeo/PROJ>`_ (see `proj#1292 <https://github.com/OSGeo/PROJ/pull/1292>`_ and `proj#2151 <https://github.com/OSGeo/PROJ/pull/2151>`_).
+  to improvements made in `Proj <https://github.com/OSGeo/PROJ>`_ (see
+  `proj#1292 <https://github.com/OSGeo/PROJ/pull/1292>`_ and
+  `proj#2151 <https://github.com/OSGeo/PROJ/pull/2151>`_).
 
 * Change tests to account for more detailed descriptions of projections in
-  `GDAL <https://github.com/OSGeo/gdal>`_ (`see GDAL#1185 <https://github.com/OSGeo/gdal/pull/1185>`_).
+  `GDAL <https://github.com/OSGeo/gdal>`_ 
+  (`see GDAL#1185 <https://github.com/OSGeo/gdal/pull/1185>`_).
 
 * Change tests to account for `GDAL <https://github.com/OSGeo/gdal>`_ now
   saving fill values for data without masked points.
@@ -144,8 +148,7 @@ Internal
   <https://github.com/SciTools/cartopy/pull/1117>`_).
 
 * Additional acceptable graphics test targets to account for very minor changes
-  in `Matplotlib <https://github.com/matplotlib/matplotlib>`_ version 3.3
-  (colormaps, fonts and axes borders).
+  in `Matplotlib`_ version 3.3 (colormaps, fonts and axes borders).
 
 
 Deprecations
@@ -192,6 +195,6 @@ Documentation
   clarify how ``Units`` are handled during cube arithmetic.
 
 .. _Read the Docs: https://scitools-iris.readthedocs.io/en/latest/
-.. _matplotlib: https://matplotlib.org/
+.. _Matplotlib: https://matplotlib.org/
 .. _CF Ancillary Data: https://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#ancillary-data
 .. _Quality Flags: https://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#flags

lib/iris/analysis/maths.py

@@ -10,7 +10,6 @@
 
 from functools import lru_cache
 import inspect
-import logging
 import math
 import operator
 import warnings
@@ -23,14 +22,15 @@
 import iris.analysis
 from iris.common import SERVICES, Resolve
 from iris.common.lenient import _lenient_client
+from iris.config import get_logger
 import iris.coords
 import iris.cube
 import iris.exceptions
 import iris.util
 
 
 # Configure the logger.
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__)
 
 
 @lru_cache(maxsize=128, typed=True)

lib/iris/common/metadata.py

@@ -9,13 +9,13 @@
 from collections.abc import Iterable, Mapping
 from copy import deepcopy
 from functools import wraps
-import logging
 import re
 
 import numpy as np
 import numpy.ma as ma
 from xxhash import xxh64_hexdigest
 
+from ..config import get_logger
 from .lenient import _LENIENT
 from .lenient import _lenient_service as lenient_service
 from .lenient import _qualname as qualname
@@ -40,7 +40,7 @@
 _TOKEN_PARSE = re.compile(r"""^[a-zA-Z0-9][\w\.\+\-@]*$""")
 
 # Configure the logger.
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__, fmt="[%(cls)s.%(funcName)s]")
 
 
 def _hexdigest(value):
@@ -1198,7 +1198,7 @@ def _check(item):
 
 class DimCoordMetadata(CoordMetadata):
     """
-    Metadata container for a :class:`~iris.coords.DimCoord"
+    Metadata container for a :class:`~iris.coords.DimCoord`
 
     """
 

lib/iris/common/resolve.py

@@ -11,14 +11,15 @@
 from dask.array.core import broadcast_shapes
 import numpy as np
 
-from iris.common import LENIENT
+from ..config import get_logger
+from . import LENIENT
 
 
 __all__ = ["Resolve"]
 
 
 # Configure the logger.
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__, fmt="[%(funcName)s]")
 
 
 _AuxCoverage = namedtuple(

lib/iris/config.py

@@ -32,11 +32,77 @@
 
 import configparser
 import contextlib
-import logging.config
+import logging
 import os.path
-import pathlib
 import warnings
-import yaml
+
+
+def get_logger(name, datefmt=None, fmt=None, level=None, propagate=None):
+    """
+    Create a :class:`logging.Logger` with a :class:`logging.StreamHandler`
+    and custom :class:`logging.Formatter`.
+
+    Args:
+
+    * name:
+        The name of the logger. Typically this is the module filename that
+        owns the logger.
+
+    Kwargs:
+
+    * datefmt:
+        The date format string of the :class:`logging.Formatter`.
+        Defaults to ``%d-%m-%Y %H:%M:%S``.
+
+    * fmt:
+        The additional format string of the :class:`logging.Formatter`.
+        This is appended to the default format string
+        ``%(asctime)s %(name)s %(levelname)s - %(message)s``.
+
+    * level:
+        The threshold level of the logger. Defaults to ``INFO``.
+
+    * propagate:
+        Sets the ``propagate`` attribute of the :class:`logging.Logger`,
+        which determines whether events logged to this logger will be
+        passed to the handlers of higher level loggers. Defaults to
+        ``False``.
+
+    """
+    if datefmt is None:
+        # Default date format string.
+        datefmt = "%d-%m-%Y %H:%M:%S"
+
+    # Default format string.
+    _fmt = "%(asctime)s %(name)s %(levelname)s - %(message)s"
+    # Append additional format string, if appropriate.
+    fmt = _fmt if fmt is None else f"{_fmt} {fmt}"
+
+    if level is None:
+        # Default logging level.
+        level = "INFO"
+
+    if propagate is None:
+        # Default logging propagate behaviour.
+        propagate = False
+
+    # Create the named logger.
+    logger = logging.getLogger(name)
+    logger.setLevel(level)
+    logger.propagate = propagate
+
+    # Create a formatter.
+    formatter = logging.Formatter(fmt=fmt, datefmt=datefmt)
+
+    # Create a logging handler.
+    handler = logging.StreamHandler()
+    # handler.setLevel(level)
+    handler.setFormatter(formatter)
+
+    # Add the handler to the logger.
+    logger.addHandler(handler)
+
+    return logger
 
 
 # Returns simple string options
@@ -84,15 +150,6 @@ def get_dir_option(section, option, default=None):
 config = configparser.ConfigParser()
 config.read([os.path.join(CONFIG_PATH, "site.cfg")])
 
-# Configure logging.
-fname_logging = pathlib.Path(CONFIG_PATH) / "logging.yaml"
-if not fname_logging.exists():
-    emsg = f"Logging configuration file '{fname_logging!s}' does not exist."
-    raise FileNotFoundError(emsg)
-with open(fname_logging) as fi:
-    logging.config.dictConfig(yaml.safe_load(fi))
-del fname_logging
-
 ##################
 # Resource options
 _RESOURCE_SECTION = "Resources"