Merge pull request #735 from DHI/docstring_pedantic

Docstrings

mikeio/__init__.py

@@ -54,7 +54,7 @@ def read(
     keepdims: bool = False,
     **kwargs: Any,
 ) -> Dataset:
-    """Read all or a subset of the data from a dfs file
+    """Read all or a subset of the data from a dfs file.
 
     All dfs files can be subsetted with the *items* and *time* arguments. But
     the following file types also have the shown additional arguments:
@@ -90,6 +90,8 @@ def read(
     fill_bad_data_value:
             fill value for to impute corrupt data, used in conjunction with error_bad_data=False
             default np.nan
+    **kwargs: Any
+        Additional keyword arguments
 
     Returns
     -------
@@ -124,8 +126,8 @@ def read(
     >>> ds = mikeio.read("MT3D_sigma_z.dfsu", layers=[-2,-1])
     >>> ds = mikeio.read("HD2D.dfsu", error_bad_data=False) # replace corrupt data with np.nan
     >>> ds = mikeio.read("HD2D.dfsu", error_bad_data=False, fill_bad_data_value=0.0) # replace corrupt data with 0.0
-    """
 
+    """
     ext = Path(filename).suffix.lower()
 
     if "dfs" not in ext:
@@ -137,7 +139,7 @@ def read(
 
 
 def open(filename: str | Path, **kwargs: Any) -> Any:
-    """Open a dfs/mesh file (and read the header)
+    """Open a dfs/mesh file (and read the header).
 
     The typical workflow for small dfs files is to read all data
     with *mikeio.read* instead of using this function. For big files, however,
@@ -152,6 +154,8 @@ def open(filename: str | Path, **kwargs: Any) -> Any:
     type : str, optional
         Dfs2 only. Additional information about the file, e.g.
         "spectral" for spectral dfs2 files. By default: None.
+    **kwargs: Any
+        Additional keyword arguments, e.g. *type="spectral"*
 
     See also
     --------
@@ -164,6 +168,7 @@ def open(filename: str | Path, **kwargs: Any) -> Any:
     >>> ds = dfs.read(items="Salinity", time="2016-01")
 
     >>> dfs = mikeio.open("pt_spectra.dfs2", type="spectral")
+
     """
     ext = Path(filename).suffix.lower()[1:]
 

mikeio/_interpolation.py

@@ -9,7 +9,7 @@
 
 
 def get_idw_interpolant(distances: np.ndarray, p: float = 2) -> np.ndarray:
-    """IDW interpolant for 2d array of distances
+    """IDW interpolant for 2d array of distances.
 
     https://pro.arcgis.com/en/pro-app/help/analysis/geostatistical-analyst/how-inverse-distance-weighted-interpolation-works.htm
 
@@ -24,6 +24,7 @@ def get_idw_interpolant(distances: np.ndarray, p: float = 2) -> np.ndarray:
     -------
     np.array
         weights
+
     """
     is_1d = distances.ndim == 1
     if is_1d:
@@ -68,7 +69,7 @@ def interp2d(
     weights: np.ndarray | None = None,
     shape: tuple[int, ...] | None = None,
 ) -> Dataset | np.ndarray:
-    """interp spatially in data (2d only)
+    """interp spatially in data (2d only).
 
     Parameters
     ----------
@@ -90,6 +91,7 @@ def interp2d(
     --------
     >>> elem_ids, weights = dfs.get_spatial_interpolant(coords)
     >>> dsi = interp2d(ds, elem_ids, weights)
+
     """
     from .dataset import DataArray, Dataset
 
@@ -157,7 +159,7 @@ def _interp_itemstep(
     elem_ids: np.ndarray,
     weights: np.ndarray | None = None,
 ) -> np.ndarray:
-    """Interpolate a single item and time step
+    """Interpolate a single item and time step.
 
     Parameters
     ----------
@@ -176,6 +178,7 @@ def _interp_itemstep(
     Notes
     -----
     This function is used internally by interp2d
+
     """
     if weights is None:
         return data[elem_ids]

mikeio/_spectral.py

@@ -23,14 +23,16 @@ def plot_2dspectrum(
     figsize: tuple[float, float] = (7, 7),
     add_colorbar: bool = True,
 ) -> Axes:
-    """
-    Plot spectrum in polar coordinates
+    """Plot spectrum in polar coordinates.
 
     Parameters
     ----------
     spectrum: np.array
-
         spectral values as 2d array with dimensions: directions, frequencies
+    frequencies: np.array
+        frequency axis
+    directions: np.array
+        direction axis
     plot_type: str, optional
         type of plot: 'contour', 'contourf', 'patch', 'shaded',
         by default: 'contourf'
@@ -61,8 +63,8 @@ def plot_2dspectrum(
     Returns
     -------
     <matplotlib.axes>
-    """
 
+    """
     import matplotlib.pyplot as plt
 
     if (frequencies is None or len(frequencies) <= 1) and (
@@ -214,7 +216,7 @@ def calc_m0_from_spectrum(
 
 
 def _f_to_df(f: np.ndarray) -> np.ndarray:
-    """Frequency bins for equidistant or logrithmic frequency axis"""
+    """Frequency bins for equidistant or logrithmic frequency axis."""
     if np.isclose(np.diff(f).min(), np.diff(f).max()):
         # equidistant frequency bins
         return (f[1] - f[0]) * np.ones_like(f)

mikeio/_time.py

@@ -8,7 +8,7 @@
 
 @dataclass
 class DateTimeSelector:
-    """Helper class for selecting time steps from a pandas DatetimeIndex"""
+    """Helper class for selecting time steps from a pandas DatetimeIndex."""
 
     index: pd.DatetimeIndex
 
@@ -18,7 +18,7 @@ def isel(
             int | Iterable[int] | str | datetime | pd.DatetimeIndex | slice | None
         ) = None,
     ) -> list[int]:
-        """Select time steps from a pandas DatetimeIndex
+        """Select time steps from a pandas DatetimeIndex.
 
         Parameters
         ----------
@@ -46,8 +46,8 @@ def isel(
         ```{python}
         dts.isel(-1)
         ```
-        """
 
+        """
         indices = list(range(len(self.index)))
 
         if x is None: