Add numpydoc validation as a pre-commit hook

.pre-commit-config.yaml

@@ -23,12 +23,16 @@ repos:
       rev: 25.12.0
       hooks:
           - id: black
-    -   repo: https://github.com/pre-commit/mirrors-mypy
-        rev: v1.19.1
-        hooks:
-        -   id: mypy
-            args: [--config-file, pyproject.toml]
-            additional_dependencies:
-              - numpy
-              - types-setuptools
-              - types-requests
+    - repo: https://github.com/pre-commit/mirrors-mypy
+      rev: v1.19.0
+      hooks:
+        - id: mypy
+          args: [--config-file, pyproject.toml]
+          additional_dependencies:
+            - numpy
+            - types-setuptools
+            - types-requests
+    - repo: https://github.com/numpy/numpydoc
+      rev: v1.7.0
+      hooks:
+        - id: numpydoc-validation

brainglobe_utils/IO/__init__.py

@@ -0,0 +1,3 @@
+"""
+I/O utilities for reading and writing BrainGlobe cell data.
+"""

brainglobe_utils/IO/cells.py

@@ -78,8 +78,21 @@ def get_cells(
 def raise_cell_read_error(
     cells_file_path: str | Path, e: Exception | None = None
 ) -> NoReturn:
-    """Raise a NotImplementedError, with an informative message including the
-    cells file path"""
+    """
+    Raise a NotImplementedError for unsupported or invalid cell file formats.
+
+    Parameters
+    ----------
+    cells_file_path : str or pathlib.Path
+        Path to the cells file that could not be read.
+    e : Exception or None, optional
+        Original exception to chain, if available.
+
+    Raises
+    ------
+    NotImplementedError
+        If the file format is unsupported or contains errors.
+    """
     logging.error(
         "File format of: {} is not supported or contains errors. Please "
         "supply an XML or YAML file, or a directory of files with positions "
@@ -353,7 +366,7 @@ def cells_to_yml(
 
 
 def cells_xml_to_df(xml_file_path):
-    """Read cells from xml file and convert to dataframe"""
+    """Read cells from xml file and convert to dataframe."""
     cells = get_cells(xml_file_path)
     return cells_to_dataframe(cells)
 
@@ -451,7 +464,7 @@ def deal_with_artifacts(cell_dict, artifact_keep=True):
     return cell_dict
 
 
-def make_type_dict(cell_list):
+def make_type_dict(cell_list):  # noqa: D401
     """Convert a list of Cells to a dictionary with keys of cell type and
     values of the list of corresponding cells."""
     types = sorted(set([cell.type for cell in cell_list]))
@@ -505,7 +518,7 @@ def find_relevant_tiffs(tiffs, cell_def):
     ]
 
 
-def _dict_to_yaml_string(data: dict) -> bytearray | bytes:
+def _dict_to_yaml_string(data: dict) -> bytearray | bytes:  # noqa: D401
     """
     Dump dict to yaml and return it as a buffer.
 

pyproject.toml

@@ -135,3 +135,19 @@ passenv =
 deps =
     napari-dev: git+https://github.com/napari/napari
 """
+
+[tool.numpydoc_validation]
+checks = [
+    "all",
+    "-EX01",  # missing Examples
+    "-SA01",  # missing See Also
+    "-ES01",  # missing Extended Summary
+    "-SS03",  # summary punctuation
+    "-SS05",  # infinitive verb rule
+    "-SS06",  # summary length
+    "-PR01",  # undocumented parameters
+    "-PR09",  # parameter punctuation
+    "-RT01",  # missing Returns section
+    "-GL01",  # summary placement
+    "-GL02",  # closing quotes placement
+]