Code qa refresh

.pre-commit-config.yaml

@@ -13,6 +13,7 @@ files: |
     (?x)(
         benchmarks\/.+\.py|
         docs\/.+\.py|
+        docs\/.+\.rst|
         lib\/.+\.py|
         noxfile\.py|
         pyproject\.toml|
@@ -97,9 +98,9 @@ repos:
       additional_dependencies: ["repo-review[cli]"]
       args: ["--show=errskip"]
 
-# TODO: pending the addition of numpydoc, including config file(s).
-#-   repo: https://github.com/numpy/numpydoc
-#    rev: v1.7.0
-#    hooks:
-#      - id: numpydoc-validation
-#        types: [file, python]
+-   repo: https://github.com/numpy/numpydoc
+    rev: v1.8.0
+    hooks:
+      - id: numpydoc-validation
+        exclude: "src/iris_grib/tests/|noxfile.py"
+        types: [file, python]

docs/index.rst

@@ -26,9 +26,10 @@ and ``iris-grib`` installed in your Python environment.
    import iris
    import iris_grib
    import warnings
-   warnings.simplefilter('ignore')
+
+   warnings.simplefilter("ignore")
    cube = iris.load_cube(iris.sample_data_path("rotated_pole.nc"))
-   iris.save(cube, 'testfile.grib', saver='grib2')
+   iris.save(cube, "testfile.grib", saver="grib2")
 
 For example, to load GRIB data :
 
@@ -185,6 +186,7 @@ You can convert Iris cubes to eccodes messages, and modify or filter them before
 
    from iris.coords import DimCoord
    import eccodes
+
    cube_height_2m5 = iris.load_cube(iris.sample_data_path("rotated_pole.nc"))
    cube_height_2m5.add_aux_coord(DimCoord([2.5], standard_name="height", units="m"), ())
 
@@ -255,4 +257,3 @@ See also:
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-

docs/ref/iris_grib.rst

@@ -22,4 +22,3 @@ In this module:
 .. autofunction:: iris_grib.save_pairs_from_cube
 
 .. autofunction:: iris_grib.save_messages
-

docs/ref/message/message.rst

@@ -15,4 +15,3 @@ In this module:
 
 .. autoclass:: iris_grib.message.Section
     :members:
-

pyproject.toml

@@ -190,3 +190,47 @@ known-first-party = ["iris_grib"]
 
 [tool.ruff.lint.pydocstyle]
 convention = "numpy"
+
+[tool.numpydoc_validation]
+checks = [
+    "all",  # Enable all numpydoc validation rules, apart from the following:
+
+    # -> Docstring text (summary) should start in the line immediately
+    #    after the opening quotes (not in the same line, or leaving a
+    #    blank line in between)
+    "GL01",  # Permit summary line on same line as docstring opening quotes.
+
+    # -> Closing quotes should be placed in the line after the last text
+    #    in the docstring (do not close the quotes in the same line as
+    #    the text, or leave a blank line between the last text and the
+    #    quotes)
+    "GL02",  # Permit a blank line before docstring closing quotes.
+
+    # -> Double line break found; please use only one blank line to
+    #    separate sections or paragraphs, and do not leave blank lines
+    #    at the end of docstrings
+    "GL03",  # Ignoring.
+
+    # -> See Also section not found
+    "SA01",  # Not all docstrings require a "See Also" section.
+
+    # -> No extended summary found
+    "ES01",  # Not all docstrings require an "Extended Summary" section.
+
+    # -> No examples section found
+    "EX01",  # Not all docstrings require an "Examples" section.
+
+    # -> No Yields section found
+    "YD01",  # Not all docstrings require a "Yields" section.
+
+    # Record temporarily ignored checks below; will be reviewed at a later date:
+    # TODO: work to remove these at a later date.
+    "GL08",  # *975    The object does not have a docstring
+    "PR01",  # *149    Parameters ... not documented
+    "RT01",  # *9      No Returns section found
+]
+exclude = [
+    '\.__eq__$',
+    '\.__ne__$',
+    '\.__repr__$',
+]

src/iris_grib/__init__.py

@@ -692,8 +692,9 @@ def core_data(self):
 
     def phenomenon_points(self, time_unit):
         """
-        Return the phenomenon time point offset from the epoch time reference
-        measured in the appropriate time units.
+        Return the phenomenon time points.
+
+        As offsets from the epoch time reference, measured in appropriate time units.
 
         """
         time_reference = "%s since epoch" % time_unit
@@ -705,8 +706,9 @@ def phenomenon_points(self, time_unit):
 
     def phenomenon_bounds(self, time_unit):
         """
-        Return the phenomenon time bound offsets from the epoch time reference
-        measured in the appropriate time units.
+        Return the phenomenon time bounds.
+
+        As offsets from the epoch time reference, measured in appropriate time units.
 
         """
         # TODO #576 Investigate when it's valid to get phenomenon_bounds
@@ -762,7 +764,7 @@ def _load_generate(filename):
 
 def load_cubes(filenames, callback=None):
     """
-    Returns an iterator over cubes from the given list of filenames.
+    Return an iterator over cubes from the given list of filenames.
 
     Args:
 
@@ -786,9 +788,21 @@ def load_cubes(filenames, callback=None):
 
 def load_pairs_from_fields(grib_messages):
     """
-    Convert an iterable of GRIB messages into an iterable of
-    (Cube, Grib message) tuples.
+    Convert an GRIB messages into (Cube, Grib message) tuples.
+
+    Parameters
+    ----------
+    grib_messages : iterable on (cube, message)
+        An iterable of :class:`GribMessage`.
 
+    Returns
+    -------
+    iterable of (cube, message)
+        An iterable of (:class:`~iris.Cube`, :class:`GribMessage`),
+        pairing each message with a corresponding generated cube.
+
+    Notes
+    -----
     This capability can be used to filter out fields before they are passed to
     the load pipeline, and amend the cubes once they are created, using
     GRIB metadata conditions.  Where the filtering
@@ -894,6 +908,7 @@ def save_pairs_from_cube(cube):
 def save_messages(messages, target, append=False):
     """
     Save messages to a GRIB2 file.
+
     The messages will be released as part of the save.
 
     Args:

src/iris_grib/_grib1_load_rules.py

@@ -17,7 +17,7 @@
 
 def grib1_convert(grib):
     """
-    Converts a GRIB1 message into the corresponding items of Cube metadata.
+    Convert a GRIB1 message into the corresponding items of Cube metadata.
 
     Args: