DOCS: Enable numpydoc validation pre-commit hook (#5762)

* add numpdoc_validate to pre-commit

* wip

* wip

* wip

* fixed doctest errors.

* fox doctests.

* Update docs/src/further_topics/filtering_warnings.rst

Co-authored-by: Martin Yeo <[email protected]>

* numpydoc_validation to adhere to RT02 rule.

* sorted temp rules to ignore.

* numpydoc_validation to adhere to GL09 rule.

* numpydoc_validation to adhere to SA04 rule.

* fixed indent.

* fixed case and indentation.

* fix doctests.

* fix doctests (last time)

* add "See Also" colons

---------

Co-authored-by: Martin Yeo <[email protected]>

Author: tkknight

.pre-commit-config.yaml

@@ -61,3 +61,10 @@ repos:
     hooks:
     -   id: sort-all
         types: [file, python]
+
+-   repo: https://github.com/numpy/numpydoc
+    rev: v1.6.0
+    hooks:
+      - id: numpydoc-validation
+        exclude: "^lib/iris/tests/|docs/gallery_code/"
+        types: [file, python]

benchmarks/asv_delegated_conda.py

@@ -47,17 +47,15 @@ def __init__(
 
         Parameters
         ----------
-        conf : Config instance
-
+        conf : Config
+            Config instance.
         python : str
             Version of Python.  Must be of the form "MAJOR.MINOR".
-
         requirements : dict
             Dictionary mapping a PyPI package name to a version
             identifier string.
-
         tagged_env_vars : dict
-            Environment variables, tagged for build vs. non-build
+            Environment variables, tagged for build vs. non-build.
 
         """
         ignored = ["`python`"]

benchmarks/benchmarks/__init__.py

@@ -10,11 +10,12 @@
 
 
 def disable_repeat_between_setup(benchmark_object):
-    """Benchmarks where object persistence would be inappropriate (decorator).
+    """Benchmark where object persistence would be inappropriate (decorator).
 
     E.g:
-        * Benchmarking data realisation
-        * Benchmarking Cube coord addition
+
+    * Benchmarking data realisation
+    * Benchmarking Cube coord addition
 
     Can be applied to benchmark classes/methods/functions.
 
@@ -107,14 +108,15 @@ def _wrapper(*args, **kwargs):
 
 
 def on_demand_benchmark(benchmark_object):
-    """Disables these benchmark(s) unless ON_DEMAND_BENCHARKS env var is set.
+    """Disable these benchmark(s) unless ON_DEMAND_BENCHARKS env var is set.
 
     This is a decorator.
 
     For benchmarks that, for whatever reason, should not be run by default.
     E.g:
-        * Require a local file
-        * Used for scalability analysis instead of commit monitoring.
+
+    * Require a local file
+    * Used for scalability analysis instead of commit monitoring.
 
     Can be applied to benchmark classes/methods/functions.
 

benchmarks/benchmarks/experimental/ugrid/regions_combine.py

@@ -92,7 +92,7 @@ def setup_cache(self):
             )
 
     def setup(self, n_cubesphere, imaginary_data=True, create_result_cube=True):
-        """Combine-tests "standard" setup operation.
+        """Combine tests "standard" setup operation.
 
         Load the source cubes (full-mesh + region) from disk.
         These are specific to the cubesize parameter.

benchmarks/benchmarks/import_iris.py

@@ -3,7 +3,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.
 
-"""import iris benchmarking."""
+"""Import iris benchmarking."""
 
 from importlib import import_module, reload
 

benchmarks/benchmarks/load/__init__.py

@@ -112,7 +112,7 @@ class ManyVars:
 
     @staticmethod
     def _create_file(save_path: str) -> None:
-        """Is run externally - everything must be self-contained."""
+        """Run externally - everything must be self-contained."""
         import numpy as np
 
         from iris import save

benchmarks/benchmarks/metadata_manager_factory.py

@@ -2,7 +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.
-"""metadata_manager_factory benchmark tests."""
+"""Metadata manager factory benchmark tests."""
 
 from iris.common import (
     AncillaryVariableMetadata,

benchmarks/benchmarks/sperf/combine_regions.py

@@ -83,7 +83,7 @@ def setup_cache(self):
             )
 
     def setup(self, n_cubesphere, imaginary_data=True, create_result_cube=True):
-        """Combine-tests "standard" setup operation.
+        """Combine tests "standard" setup operation.
 
         Load the source cubes (full-mesh + region) from disk.
         These are specific to the cubesize parameter.

benchmarks/bm_runner.py

@@ -66,7 +66,7 @@ def _check_requirements(package: str) -> None:
 
 
 def _prep_data_gen_env() -> None:
-    """Create/access a separate, unchanging environment for generating test data."""
+    """Create or access a separate, unchanging environment for generating test data."""
     python_version = "3.11"
     data_gen_var = "DATA_GEN_PYTHON"
     if data_gen_var in environ:

docs/gallery_code/general/plot_custom_aggregation.py

@@ -39,14 +39,14 @@ def count_spells(data, threshold, axis, spell_length):
     Parameters
     ----------
     data : array
-        raw data to be compared with value threshold.
+        Raw data to be compared with value threshold.
     threshold : float
-        threshold point for 'significant' datapoints.
+        Threshold point for 'significant' datapoints.
     axis : int
-        number of the array dimension mapping the time sequences.
-        (Can also be negative, e.g. '-1' means last dimension)
+        Number of the array dimension mapping the time sequences.
+        (Can also be negative, e.g. '-1' means last dimension).
     spell_length : int
-        number of consecutive times at which value > threshold to "count".
+        Number of consecutive times at which value > threshold to "count".
 
     """
     if axis < 0:

docs/gallery_code/general/plot_rotated_pole_mapping.py

@@ -1,6 +1,6 @@
 """
 Rotated Pole Mapping
-=====================
+====================
 
 This example uses several visualisation methods to achieve an array of
 differing images, including:

docs/src/conf.py

@@ -17,7 +17,7 @@
 # serve to show the default.
 # ----------------------------------------------------------------------------
 
-"""sphinx config."""
+"""Config for sphinx."""
 
 import datetime
 from importlib.metadata import version as get_version

docs/src/developers_guide/documenting/docstrings_attribute.py

@@ -1,4 +1,4 @@
-"""docstring attribute example."""
+"""Docstring attribute example."""
 
 
 class ExampleClass:

docs/src/developers_guide/documenting/docstrings_sample_routine.py

@@ -1,4 +1,4 @@
-"""docstring routine example."""
+"""Docstring routine example."""
 
 
 def sample_routine(arg1, arg2, kwarg1="foo", kwarg2=None):
@@ -12,16 +12,16 @@ def sample_routine(arg1, arg2, kwarg1="foo", kwarg2=None):
         First argument description.
     arg2 : numpy.ndarray
         Second argument description.
-    kwarg1: str, optional
+    kwarg1 : str, optional
         The first keyword argument. This argument description
         can be multi-lined.
-    kwarg2 : bool, optional
+    **kwarg2 : bool, optional
         The second keyword argument.
 
     Returns
     -------
     numpy.ndarray
-        numpy.ndarray of arg1 * arg2
+        A numpy.ndarray of arg1 * arg2.
 
     """
     pass

docs/src/further_topics/filtering_warnings.rst

@@ -47,9 +47,9 @@ Warnings:
 
     >>> my_operation()
     ...
-    iris/coord_systems.py:442: IrisUserWarning: Setting inverse_flattening does not affect other properties of the GeogCS object. To change other properties set them explicitly or create a new GeogCS instance.
+    iris/coord_systems.py:444: IrisUserWarning: Setting inverse_flattening does not affect other properties of the GeogCS object. To change other properties set them explicitly or create a new GeogCS instance.
       warnings.warn(wmsg, category=iris.warnings.IrisUserWarning)
-    iris/coord_systems.py:768: IrisDefaultingWarning: Discarding false_easting and false_northing that are not used by Cartopy.
+    iris/coord_systems.py:770: IrisDefaultingWarning: Discarding false_easting and false_northing that are not used by Cartopy.
       warnings.warn(
 
 Warnings can be suppressed using the Python warnings filter with the ``ignore``
@@ -110,7 +110,7 @@ You can target specific Warning messages, e.g.
     ...     warnings.filterwarnings("ignore", message="Discarding false_easting")
     ...     my_operation()
     ...
-    iris/coord_systems.py:442: IrisUserWarning: Setting inverse_flattening does not affect other properties of the GeogCS object. To change other properties set them explicitly or create a new GeogCS instance.
+    iris/coord_systems.py:444: IrisUserWarning: Setting inverse_flattening does not affect other properties of the GeogCS object. To change other properties set them explicitly or create a new GeogCS instance.
       warnings.warn(wmsg, category=iris.warnings.IrisUserWarning)
 
 ::
@@ -125,16 +125,16 @@ Or you can target Warnings raised by specific lines of specific modules, e.g.
 .. doctest:: filtering_warnings
 
     >>> with warnings.catch_warnings():
-    ...     warnings.filterwarnings("ignore", module="iris.coord_systems", lineno=442)
+    ...     warnings.filterwarnings("ignore", module="iris.coord_systems", lineno=444)
     ...     my_operation()
     ...
-    iris/coord_systems.py:768: IrisDefaultingWarning: Discarding false_easting and false_northing that are not used by Cartopy.
+    iris/coord_systems.py:770: IrisDefaultingWarning: Discarding false_easting and false_northing that are not used by Cartopy.
       warnings.warn(
 
 ::
 
-    python -W ignore:::iris.coord_systems:442
-    export PYTHONWARNINGS=ignore:::iris.coord_systems:442
+    python -W ignore:::iris.coord_systems:444
+    export PYTHONWARNINGS=ignore:::iris.coord_systems:444
 
 Warnings from a Common Source
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -188,7 +188,7 @@ module during execution:
     ...     )
     ...     my_operation()
     ...
-    iris/coord_systems.py:442: IrisUserWarning: Setting inverse_flattening does not affect other properties of the GeogCS object. To change other properties set them explicitly or create a new GeogCS instance.
+    iris/coord_systems.py:444: IrisUserWarning: Setting inverse_flattening does not affect other properties of the GeogCS object. To change other properties set them explicitly or create a new GeogCS instance.
       warnings.warn(wmsg, category=iris.warnings.IrisUserWarning)
 
 ----

lib/iris/_concatenate.py

@@ -160,7 +160,7 @@ class _DerivedCoordAndDims(
     Parameters
     ----------
     coord : :class:`iris.coord.DimCoord` or :class:`iris.coord.AuxCoord`
-    dims: tuple
+    dims : tuple
         A tuple of the data dimension(s) spanned by the coordinate.
     aux_factory : :class:`iris.aux_factory.AuxCoordFactory`
 
@@ -196,7 +196,7 @@ def __new__(cls, ancil, dims):
 
         Parameters
         ----------
-        ancil : :class:`iris.coord.CellMeasure` or :class:`iris.coord.AncillaryVariable`.
+        ancil : :class:`iris.coord.CellMeasure` or :class:`iris.coord.AncillaryVariable`
         dims :
             The dimension(s) associated with ancil.
 
@@ -271,7 +271,6 @@ class _CoordExtent(namedtuple("CoordExtent", ["points", "bounds"])):
     ----------
     points : :class:`_Extent`
         The :class:`_Extent` of the coordinate point values.
-
     bounds :
         A list containing the :class:`_Extent` of the coordinate lower
         bound and the upper bound. Defaults to None if no associated
@@ -297,7 +296,7 @@ def concatenate(
     cubes : iterable of :class:`iris.cube.Cube`
         An iterable containing one or more :class:`iris.cube.Cube` instances
         to be concatenated together.
-    error_on_mismatch: bool, default=False
+    error_on_mismatch : bool, default=False
         If True, raise an informative
         :class:`~iris.exceptions.ContatenateError` if registration fails.
     check_aux_coords : bool, default=True
@@ -491,7 +490,7 @@ def _coordinate_differences(self, other, attr, reason="metadata"):
             between `self` and `other`.
         reason : str, default="metadata"
             The reason to give for mismatch (function is normally, but not
-            always, testing metadata)
+            always, testing metadata).
 
         Returns
         -------
@@ -763,9 +762,9 @@ def axis(self):
         return self._axis
 
     def concatenate(self):
-        """Concatenates all the source-cubes registered with the :class:`_ProtoCube`.
+        """Concatenate all the source-cubes registered with the :class:`_ProtoCube`.
 
-        Concatenates all the source-cubes registered with the
+        Concatenate all the source-cubes registered with the
         :class:`_ProtoCube` over the nominated common dimension.
 
         Returns

lib/iris/_constraints.py

@@ -282,9 +282,9 @@ def __init__(self, coord_name, coord_thing):
         Parameters
         ----------
         coord_name : str
-            The name of the coordinate to constrain
+            The name of the coordinate to constrain.
         coord_thing :
-            The object to compare
+            The object to compare.
 
         """
         self.coord_name = coord_name
@@ -492,9 +492,9 @@ def list_of_constraints(constraints):
 
 
 def as_constraint(thing):
-    """Casts an object into a cube constraint where possible.
+    """Cast an object into a cube constraint where possible.
 
-    Casts an object into a cube constraint where possible, otherwise
+    Cast an object into a cube constraint where possible, otherwise
     a TypeError will be raised.
 
     If the given object is already a valid constraint then the given object

lib/iris/_data_manager.py

@@ -171,7 +171,7 @@ def _deepcopy(self, memo, data=None):
 
     @property
     def data(self):
-        """Returns the real data. Any lazy data being managed will be realised.
+        """Return the real data. Any lazy data being managed will be realised.
 
         Returns
         -------

lib/iris/_lazy_data.py

@@ -338,7 +338,7 @@ def as_concrete_data(data):
     Parameters
     ----------
     data :
-        A dask array, NumPy `ndarray` or masked array
+        A dask array, NumPy `ndarray` or masked array.
 
     Returns
     -------

lib/iris/_merge.py

@@ -877,7 +877,7 @@ def _build_separable_group(
         dependency on any other candidate dimensions within the space.
     group :
         A set of related (chained) inseparable candidate dimensions.
-    separable_consistent_groups:
+    separable_consistent_groups :
         A list of candidate dimension groups that are consistently separable.
     positions :
         A list containing a dictionary of candidate dimension key to
@@ -1047,7 +1047,7 @@ def derive_space(groups, relation_matrix, positions, function_matrix=None):
     ----------
     groups :
         A list of all related (chained) inseparable candidate dimensions.
-    relation_matrix:
+    relation_matrix :
         The relation dictionary for each candidate dimension.
     positions :
         A list containing a dictionary of candidate dimension key to
@@ -1294,7 +1294,7 @@ def register(self, cube, error_on_mismatch=False):
         cube :
             Candidate :class:`iris.cube.Cube` to be associated with
             this :class:`ProtoCube`.
-        error_on_mismatch :bool, default=False
+        error_on_mismatch : bool, default=False
             If True, raise an informative
             :class:`~iris.exceptions.MergeError` if registration fails.
 
@@ -1335,7 +1335,8 @@ def _guess_axis(self, name):
 
         Returns
         -------
-        axis : {'T', 'Z', 'Y', 'X'} or None.
+        str or None
+            {'T', 'Z', 'Y', 'X'} or None.
 
         """
         axis = None