Add and improve Numpydoc-style docstrings across core modules

.github/workflows/numpydoc.yml

@@ -0,0 +1,29 @@
+name: Numpydoc Lint
+
+on: [pull_request]
+jobs:
+  numpydoc-lint:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - uses: awalsh128/cache-apt-pkgs-action@latest
+        with:
+          packages: fd-find
+          version: 1.0
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.13" # Adjust version as needed
+
+      - name: Install dependencies
+        run: |
+          pip install numpydoc
+          sudo apt-get install
+
+      - name: Run Numpydoc Lint
+        run: |
+          fdfind . qcore/ -E "__init__.py" --extension py | xargs numpydoc lint

qcore/constants.py

@@ -13,21 +13,58 @@ class ExtendedEnum(Enum):
 
     @classmethod
     def has_value(cls, value: Any) -> bool:
+        """Check if enum has value.
+
+        Parameters
+        ----------
+        value : Any
+            Value to check.
+
+        Returns
+        -------
+        bool
+            True if Enum has value.
+        """
         return any(value == item.value for item in cls)
 
     @classmethod
     def is_substring(cls, parent_string: str) -> bool:
-        """Check if an enum's string value is contained in the given string"""
+        """Check if an enum's string value is contained in the given string
+
+        Parameters
+        ----------
+        parent_string : str
+            The string to search for the value.
+
+        Returns
+        -------
+        bool
+            True if any enum value is a substring of `parent_string`.
+        """
         return any(
             isinstance(item.value, str) and item.value in parent_string
             for item in cls
         )
 
     @classmethod
     def get_names(cls) -> list[str]:
+        """Get the names for every enum member.
+
+        Returns
+        -------
+        list of str
+            The enum member names.
+        """
         return [item.name for item in cls]
 
     def __str__(self) -> str:
+        """Get a string representation of Enum value.
+
+        Returns
+        -------
+        str
+            The enum member name.
+        """
         return self.name
 
 
@@ -46,23 +83,58 @@ def __new__(cls, value: Any, str_value: str):  # noqa: D102 # numpydoc ignore=GL
 
     @classmethod
     def has_str_value(cls, str_value: str) -> bool:
+        """Check if any enum member has a given string value.
+
+        Parameters
+        ----------
+        str_value : str
+            The value to check.
+
+        Returns
+        -------
+        bool
+            True if the Enum contains a member whose string value matches `str_value`.
+        """
         return any(str_value == item.str_value for item in cls)
 
     @classmethod
-    def from_str(cls, str_value):
-        if not cls.has_str_value(str_value):
-            raise ValueError(f"{str_value} is not a valid {cls.__name__}")
-        else:
-            for item in cls:
-                if item.str_value == str_value:
-                    return item
+    def from_str(cls, str_value: str) -> Any:
+        """Lookup an enum member from its str_value.
+
+        Parameters
+        ----------
+        str_value : str
+            The string value of the enum member.
+
+        Returns
+        -------
+        Any
+            The enum member with matching `str_value`.
+
+        Raises
+        ------
+        ValueError
+            If the enum does not contain a member with the given string value.
+        """
+        for item in cls:
+            if item.str_value == str_value:
+                return item
+        raise ValueError(f"{str_value} is not a valid {cls.__name__}")
 
     @classmethod
     def iterate_str_values(cls, ignore_none: bool = True) -> Generator[Any, None, None]:
-        """Iterates over the string values of the enum,
-        ignores entries without a string value by default
+        """Iterates over the member variables of the enum.
+
+        Parameters
+        ----------
+        ignore_none : bool
+            If True, ignore all member variables whose str_value is None.
+
+        Yields
+        ------
+        Any
+            An enum member variable.
         """
-        for item in cls:
-            if ignore_none and item.str_value is None:
-                continue
-            yield item.str_value
+        yield from (
+            item for item in cls if not (ignore_none and item.str_value is None)
+        )

qcore/coordinates.py

@@ -2,13 +2,6 @@
 Module for coordinate conversions between WGS84 (latitude and longitude) and
 NZTM (New Zealand Transverse Mercator) coordinate systems.
 
-Functions
-----------
-- wgs_depth_to_nztm(wgs_depth_coordinates: np.ndarray) -> np.ndarray:
-    Converts WGS84 coordinates (latitude, longitude, depth) to NZTM coordinates.
-- nztm_to_wgs_depth(nztm_coordinates: np.ndarray) -> np.ndarray:
-    Converts NZTM coordinates (y, x, depth) to WGS84 coordinates.
-
 References
 ----------
 This module provides functions for converting coordinates between WGS84 and NZTM coordinate systems.
@@ -197,7 +190,7 @@ def great_circle_bearing_to_nztm_bearing(
         The origin point to compute the bearing from.
     distance : float
         The distance to shift.
-    ll_bearing : float
+    great_circle_bearing : float
         The great circle bearing for the final point.
 
     Returns