ruff checks for numpydocs (#5630)

* wip

* ruff compliant.

* enabled ignore

.ruff.toml

@@ -28,6 +28,14 @@ lint.ignore = [
     # pydocstyle (D)
     # https://docs.astral.sh/ruff/rules/#pydocstyle-d
     "D",
+    # Permanent
+    "D105",  # Missing docstring in magic method
+
+    # Temporary, to be removed when we are more compliant
+    "D417",  # Missing argument descriptions in the docstring
+    "D101",  # Missing docstring in public class
+    "D102",  # Missing docstring in public method
+    "D106",  # Missing docstring in public nested class
 
     # pyupgrade (UP)
     # https://docs.astral.sh/ruff/rules/#pyupgrade-up

lib/iris/config.py

@@ -2,8 +2,7 @@
 #
 # This file is part of Iris and is released under the BSD license.
 # See LICENSE in the root of the repository for full licensing details.
-"""
-Provides access to Iris-specific configuration values.
+"""Provides access to Iris-specific configuration values.
 
 The default configuration values can be overridden by creating the file
 ``iris/etc/site.cfg``. If it exists, this file must conform to the format
@@ -42,8 +41,7 @@
 def get_logger(
     name, datefmt=None, fmt=None, level=None, propagate=None, handler=True
 ):
-    """
-    Create a custom class for logging.
+    """Create a custom class for logging.
 
     Create a :class:`logging.Logger` with a :class:`logging.StreamHandler`
     and custom :class:`logging.Formatter`.
@@ -114,8 +112,7 @@ def get_logger(
 
 # Returns simple string options
 def get_option(section, option, default=None):
-    """
-    Return the option value for the given section.
+    """Return the option value for the given section.
 
     Returns the option value for the given section, or the default value
     if the section/option is not present.
@@ -129,8 +126,7 @@ def get_option(section, option, default=None):
 
 # Returns directory path options
 def get_dir_option(section, option, default=None):
-    """
-    Return the directory path from the given option and section.
+    """Return the directory path from the given option and section.
 
     Returns the directory path from the given option and section, or
     returns the given default value if the section/option is not present
@@ -194,8 +190,7 @@ class NetCDF:
     """Control Iris NetCDF options."""
 
     def __init__(self, conventions_override=None):
-        """
-        Set up NetCDF processing options for Iris.
+        """Set up NetCDF processing options for Iris.
 
         Parameters
         ----------
@@ -274,8 +269,7 @@ def _defaults_dict(self):
 
     @contextlib.contextmanager
     def context(self, **kwargs):
-        """
-        Allow temporary modification of the options via a context manager.
+        """Allow temporary modification of the options via a context manager.
 
         Accepted kwargs are the same as can be supplied to the Option.
 

lib/iris/fileformats/netcdf/_dask_locks.py

@@ -2,8 +2,7 @@
 #
 # This file is part of Iris and is released under the BSD license.
 # See LICENSE in the root of the repository for full licensing details.
-"""
-Module containing code to create locks enabling dask workers to co-operate.
+"""Module containing code to create locks enabling dask workers to co-operate.
 
 This matter is complicated by needing different solutions for different dask
 scheduler types, i.e. local 'threads' scheduler, local 'processes' or
@@ -81,8 +80,7 @@ def dask_scheduler_is_distributed():
 
 
 def get_dask_array_scheduler_type():
-    """
-    Work out what type of scheduler an array.compute*() will use.
+    """Work out what type of scheduler an array.compute*() will use.
 
     Returns one of 'distributed', 'threads' or 'processes'.
     The return value is a valid argument for dask.config.set(scheduler=<type>).
@@ -117,8 +115,7 @@ def get_dask_array_scheduler_type():
 
 
 def get_worker_lock(identity: str):
-    """
-    Return a mutex Lock which can be shared by multiple Dask workers.
+    """Return a mutex Lock which can be shared by multiple Dask workers.
 
     The type of Lock generated depends on the dask scheduler type, which must
     therefore be set up before this is called.

lib/iris/fileformats/netcdf/loader.py

@@ -2,8 +2,7 @@
 #
 # This file is part of Iris and is released under the BSD license.
 # See LICENSE in the root of the repository for full licensing details.
-"""
-Support loading Iris cubes from NetCDF files using the CF conventions for metadata interpretation.
+"""Support loading Iris cubes from NetCDF files using the CF conventions for metadata interpretation.
 
 See : `NetCDF User's Guide <https://docs.unidata.ucar.edu/nug/current/>`_
 and `netCDF4 python module <https://github.com/Unidata/netcdf4-python>`_.
@@ -159,8 +158,7 @@ def _set_attributes(attributes, key, value):
 
 
 def _add_unused_attributes(iris_object, cf_var):
-    """
-    Populate the attributes of a cf element with the "unused" attributes.
+    """Populate the attributes of a cf element with the "unused" attributes.
 
     Populate the attributes of a cf element with the "unused" attributes
     from the associated CF-netCDF variable. That is, all those that aren't CF
@@ -200,8 +198,7 @@ def _get_actual_dtype(cf_var):
 
 
 def _get_cf_var_data(cf_var, filename):
-    """
-    Get an array representing the data of a CF variable.
+    """Get an array representing the data of a CF variable.
 
     This is typically a lazy array based around a NetCDFDataProxy, but if the variable
     is "sufficiently small", we instead fetch the data as a real (numpy) array.
@@ -292,8 +289,8 @@ def _get_cf_var_data(cf_var, filename):
 
 
 class _OrderedAddableList(list):
-    """
-    A custom container object for actions recording.
+    """A custom container object for actions recording.
+
     Used purely in actions debugging, to accumulate a record of which actions
     were activated.
 
@@ -521,8 +518,7 @@ def coord_from_term(term):
 
 
 def _translate_constraints_to_var_callback(constraints):
-    """
-    Translate load constraints into a simple data-var filter function, if possible.
+    """Translate load constraints into a simple data-var filter function, if possible.
 
     Returns
     -------
@@ -566,8 +562,7 @@ def inner(cf_datavar):
 
 
 def load_cubes(file_sources, callback=None, constraints=None):
-    """
-    Load cubes from a list of NetCDF filenames/OPeNDAP URLs.
+    """Load cubes from a list of NetCDF filenames/OPeNDAP URLs.
 
     Parameters
     ----------
@@ -578,6 +573,8 @@ def load_cubes(file_sources, callback=None, constraints=None):
     callback : function, optional
         Function which can be passed on to :func:`iris.io.run_callback`.
 
+    constraints : optional
+
     Returns
     -------
     Generator of loaded NetCDF :class:`iris.cube.Cube`.
@@ -678,8 +675,7 @@ class Modes(Enum):
         AS_DASK = auto()
 
     def __init__(self, var_dim_chunksizes=None):
-        """
-        Provide user control of Dask chunking.
+        """Provide user control of Dask chunking.
 
         The NetCDF loader is controlled by the single instance of this: the
         :data:`~iris.fileformats.netcdf.loader.CHUNK_CONTROL` object.
@@ -709,8 +705,7 @@ def set(
         var_names: Union[str, Iterable[str]] = None,
         **dimension_chunksizes: Mapping[str, int],
     ) -> None:
-        """
-        Control the Dask chunk sizes applied to NetCDF variables during loading.
+        r"""Control the Dask chunk sizes applied to NetCDF variables during loading.
 
         Parameters
         ----------
@@ -784,8 +779,7 @@ def set(
 
     @contextmanager
     def from_file(self) -> None:
-        """
-        Ensures the chunk sizes are loaded in from NetCDF file variables.
+        r"""Ensure the chunk sizes are loaded in from NetCDF file variables.
 
         Raises
         ------
@@ -808,8 +802,7 @@ def from_file(self) -> None:
 
     @contextmanager
     def as_dask(self) -> None:
-        """
-        Relies on Dask :external+dask:doc:`array` to control chunk sizes.
+        """Relies on Dask :external+dask:doc:`array` to control chunk sizes.
 
         Notes
         -----