adjust docstrings and numpydoc configuration

pyproject.toml

@@ -181,6 +181,22 @@ warn_unused_configs = true
 module = []
 ignore_missing_imports = true
 
+[tool.numpydoc_validation]
+checks = [
+  "all", # report on all checks, except the below
+  "ES01",
+  "EX01",
+  "GL01",
+  "SA01"
+]
+exclude = [
+  # don't report on objects that match any of these regex
+  '\.undocumented_method$',
+  '\.__repr__$',
+  # any object starting with an underscore is a private object
+  '\._\w+'
+]
+
 [tool.pytest.ini_options]
 addopts = [
   "--verbose",

xhydro/cc.py

@@ -1,4 +1,5 @@
 """Module to compute climate change statistics using xscen functions."""
+import xarray
 
 # Special imports from xscen
 from xscen import (  # FIXME: To be replaced with climatological_op once available
@@ -17,8 +18,20 @@
 
 
 # FIXME: To be deleted once climatological_op is available in xscen
-def climatological_op(ds, **kwargs):
-    """Compute climatological operation.
+def climatological_op(ds: xarray.Dataset, **kwargs: dict) -> xarray.Dataset:
+    r"""Compute climatological operation.
+
+    Parameters
+    ----------
+    ds : xarray.Dataset
+        Input dataset.
+    \*\*kwargs : dict
+        Keyword arguments passed to :py:func:`xscen.aggregate.climatological_mean`.
+
+    Returns
+    -------
+    xarray.Dataset
+        Output dataset.
 
     Notes
     -----

xhydro/indicators.py

@@ -64,36 +64,37 @@ def get_yearly_op(
     missing_options: Optional[dict] = None,
     interpolate_na: bool = False,
 ) -> xr.Dataset:
-    """
-    Compute yearly operations on a variable.
+    """Compute yearly operations on a variable.
 
     Parameters
     ----------
-    ds: xr.Dataset
+    ds : xr.Dataset
         Dataset containing the variable to compute the operation on.
-    op: str
+    op : str
         Operation to compute. One of ["max", "min", "mean", "sum"].
-    input_var: str
+    input_var : str
         Name of the input variable. Defaults to "streamflow".
-    window: int
+    window : int
         Size of the rolling window. A "mean" operation is performed on the rolling window before the call to xclim.
         This parameter cannot be used with the "sum" operation.
-    timeargs: dict, optional
+    timeargs : dict, optional
         Dictionary of time arguments for the operation.
         Keys are the name of the period that will be added to the results (e.g. "winter", "summer", "annual").
         Values are up to two dictionaries, with both being optional.
         The first is {'freq': str}, where str is a frequency supported by xarray (e.g. "YS", "AS-JAN", "AS-DEC").
         It needs to be a yearly frequency. Defaults to "AS-JAN".
-        The second is an indexer as supported by :py:func:`xclim.core.calendar.select_time`. Defaults to {}, which means the whole year.
+        The second is an indexer as supported by :py:func:`xclim.core.calendar.select_time`.
+        Defaults to {}, which means the whole year.
         See :py:func:`xclim.core.calendar.select_time` for more information.
-        Examples: {"winter": {"freq": "AS-DEC", "date_bounds": ['12-01', '02-28']}}, {"jan": {"freq": "YS", "month": 1}}, {"annual": {}}.
-    missing: str
+        Examples: {"winter": {"freq": "AS-DEC", "date_bounds": ["12-01", "02-28"]}}, {"jan": {"freq": "YS", "month": 1}}, {"annual": {}}.
+    missing : str
         How to handle missing values. One of "skip", "any", "at_least_n", "pct", "wmo".
         See :py:func:`xclim.core.missing` for more information.
-    missing_options: dict, optional
+    missing_options : dict, optional
         Dictionary of options for the missing values' method. See :py:func:`xclim.core.missing` for more information.
-    interpolate_na: bool
-        Whether to interpolate missing values before computing the operation. Only used with the "sum" operation. Defaults to False.
+    interpolate_na : bool
+        Whether to interpolate missing values before computing the operation. Only used with the "sum" operation.
+        Defaults to False.
 
     Returns
     -------
@@ -105,7 +106,6 @@ def get_yearly_op(
     -----
     If you want to perform a frequency analysis on a frequency that is finer than annual, simply use multiple timeargs
     (e.g. 1 per month) to create multiple distinct variables.
-
     """
     missing_options = missing_options or {}
     timeargs = timeargs or {"annual": {}}
@@ -174,7 +174,8 @@ def get_yearly_op(
             and freq != "AS-DEC"
         ):
             warnings.warn(
-                "The frequency is not AS-DEC, but the season indexer includes DJF. This will lead to misleading results."
+                "The frequency is not AS-DEC, but the season indexer includes DJF. "
+                "This will lead to misleading results."
             )
         elif (
             "doy_bounds" in indexer.keys()

xhydro/testing/helpers.py

@@ -98,7 +98,18 @@ def generate_registry(
 
 
 def load_registry(file: Optional[Union[str, Path]] = None) -> dict[str, str]:
-    """Load the registry file for the test data."""
+    """Load the registry file for the test data.
+
+    Parameters
+    ----------
+    file : str or Path, optional
+        Path to the registry file. If not provided, the registry file found within the package data will be used.
+
+    Returns
+    -------
+    dict
+        Dictionary of filenames and hashes.
+    """
     # Get registry file from package_data
     if file is None:
         registry_file = ilr.files("xhydro").joinpath("testing/registry.txt")
@@ -157,8 +168,25 @@ def populate_testing_data(
     temp_folder: Optional[Path] = None,
     branch: str = TESTDATA_BRANCH,
     _local_cache: Path = _default_cache_dir,
-):
-    """Populate the local cache with the testing data."""
+) -> None:
+    """Populate the local cache with the testing data.
+
+    Parameters
+    ----------
+    registry : str or Path, optional
+        Path to the registry file. If not provided, the registry file from package_data will be used.
+    temp_folder : Path, optional
+        Path to a temporary folder to use as the local cache. If not provided, the default location will be used.
+    branch : str, optional
+        Branch of hydrologie/xhydro-testdata to use when fetching testing datasets.
+    _local_cache : Path, optional
+        Path to the local cache. Defaults to the default location.
+
+    Returns
+    -------
+    None
+        The testing data will be downloaded to the local cache.
+    """
     # Get registry file from package_data or provided path
     registry = load_registry(registry)
 

xhydro/testing/utils.py

@@ -30,7 +30,8 @@ def publish_release_notes(
 
     Returns
     -------
-    str, optional
+    str or None
+        Formatted release notes as a string, if `file` is not provided.
 
     Notes
     -----