From f82e50156bc0be8e4f45ca6f9ef3c24730e1c788 Mon Sep 17 00:00:00 2001
From: Knut-Frode Dagestad <knutfrode@gmail.com>
Date: Tue, 8 Oct 2024 22:08:02 +0200
Subject: [PATCH] Updated several docstrings to Xarray style

---
 docs/source/conf.py |  5 ++--
 trajan/traj.py      | 68 +++++++++++++++++++++++++++++++++------------
 2 files changed, 53 insertions(+), 20 deletions(-)

diff --git a/docs/source/conf.py b/docs/source/conf.py
index 0aac285..f7cbd49 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -21,7 +21,7 @@
 autoapi_dirs = [ '../../trajan' ]
 autoapi_keep_files = False  # set to True when debugging autoapi generated files
 autoapi_python_class_content = 'both'
-autodoc_typehints = 'description'
+autodoc_typehints = 'none'
 
 import warnings
 warnings.filterwarnings("ignore", category=UserWarning,
@@ -64,6 +64,7 @@
     'scipy': ('https://docs.scipy.org/doc/scipy', None),
     'cftime': ('https://unidata.github.io/cftime', None),
     'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
+    'pyproj': ('https://pyproj4.github.io/pyproj/stable/', None),
     'xarray': ('https://xarray.pydata.org/en/stable/', None),
     'pandas': ("https://pandas.pydata.org/pandas-docs/stable", None),
 }
@@ -95,7 +96,7 @@
 napoleon_google_docstring = False
 napoleon_numpy_docstring = True
 napoleon_use_param = False
-napoleon_use_ivar = True
+napoleon_use_ivar = False
 napoleon_use_rtype = False
 napoleon_preprocess_types = True
 napoleon_type_aliases = {
diff --git a/trajan/traj.py b/trajan/traj.py
index 0f7ad5f..f625c7e 100644
--- a/trajan/traj.py
+++ b/trajan/traj.py
@@ -88,7 +88,7 @@ def animate(self):
     @property
     def tx(self):
         """
-        Trajectory x coordinates (usually longitude) - test.
+        Trajectory x coordinates (usually longitude).
 
         See Also
         --------
@@ -121,6 +121,10 @@ def ty(self):
     def tlon(self):
         """
         Retrieve the trajectories in geographic coordinates (longitudes).
+
+        See Also
+        --------
+        tx, tlat
         """
         if self.crs.is_geographic:
             return self.tx
@@ -137,6 +141,10 @@ def tlon(self):
     def tlat(self) -> xr.DataArray:
         """
         Retrieve the trajectories in geographic coordinates (latitudes).
+
+        See Also
+        --------
+        ty, tlon
         """
         if self.crs.is_geographic:
             return self.ty
@@ -155,14 +163,14 @@ def transform(self, to_crs, x, y):
 
         Parameters
         ----------
-        to_crs : pyproj.CRS
+        to_crs : pyproj.crs.CRS
 
-        x, y : arrays
+        x, y : array-like
             Coordinates in `self` CRS
 
         Returns
         -------
-        xn, yn : arrays
+        xn, yn : array-like
             Coordinates in `to_crs`
         """
         t = pyproj.Transformer.from_crs(self.crs, to_crs, always_xy=True)
@@ -174,23 +182,27 @@ def itransform(self, from_crs, x, y):
 
         Parameters
         ----------
-        from_crs : `pyproj.CRS`
+        from_crs : pyproj.crs.CRS
 
-        x, y : arrays
-            Coordinates in `from_crs` CRS
+        x, y : array-like
+            Coordinates in from_crs CRS
 
         Returns
         -------
-        xn, yn : arrays
+        xn, yn : array-like
             Coordinates in this datasets CRS
         """
         t = pyproj.Transformer.from_crs(from_crs, self.crs, always_xy=True)
         return t.transform(x, y)
 
     @property
-    def crs(self) -> pyproj.CRS:
+    def crs(self) -> pyproj.crs.CRS:
         """
-        Retrieve the pyproj.CRS object from the CF-defined grid-mapping in the dataset.
+        Retrieve the pyproj.crs.CRS object from the CF-defined grid-mapping in the dataset.
+
+        Returns
+        -------
+        pyproj.crs.CRS
         """
         if len(self.ds.cf.grid_mapping_names) == 0:
             logger.debug(
@@ -208,7 +220,7 @@ def crs(self) -> pyproj.CRS:
         else:
             gm = self.ds.cf['grid_mapping']
             logger.debug(f'Constructing CRS from grid_mapping: {gm}')
-            return pyproj.CRS.from_cf(gm.attrs)
+            return pyproj.crs.CRS.from_cf(gm.attrs)
 
     def set_crs(self, crs) -> xr.Dataset:
         """
@@ -216,15 +228,16 @@ def set_crs(self, crs) -> xr.Dataset:
 
         Parameters
         ----------
-        crs: pyproj.CRS
+        crs : pyproj.crs.CRS
 
         Returns
         -------
-        updated dataset
-
-        .. warning::
+        Dataset
+            Updated dataset
 
-            This does not transform the coordinates, make sure that `crs` is matching the data in the dataset.
+        Warning
+        -------
+        This does not transform the coordinates, make sure that `crs` is matching the data in the dataset.
         """
 
         # TODO: Ideally this would be handled by cf-xarray or rio-xarray.
@@ -282,6 +295,19 @@ def assign_cf_attrs(self,
                         **kwargs) -> xr.Dataset:
         """
         Return a new dataset with CF-standard and common attributes set.
+
+        Parameters
+        ----------
+        *kwargs
+            Attribute names and values
+
+        Returns
+        -------
+        Dataset
+            Updated dataset with provided attributes, in addition to several CF standard attributes,
+            including Conventions, featureType, geospatial_lat_min etc.
+             
+
         """
         ds = self.ds.copy(deep=True)
 
@@ -332,7 +358,13 @@ def assign_cf_attrs(self,
         return ds
 
     def index_of_last(self):
-        """Find index of last valid position along each trajectory."""
+        """Find index of last valid position along each trajectory.
+
+        Returns
+        -------
+        array-like
+            Array of the index of the last valid position along each trajectory.
+        """
         return np.ma.notmasked_edges(np.ma.masked_invalid(self.ds.lon.values),
                                      axis=1)[1][1]
 
@@ -612,7 +644,7 @@ def skill(self, other, method='liu-weissberg', **kwargs) -> xr.Dataset:
         Returns
         -------
 
-        skill : :class:`xarray.Dataset`
+        skill : Dataset
             The skill-score in the same dimensions as this dataset.
 
         Notes