docs: fix docstrings formatting

Author: amorison

stagpy/_helpers.py

@@ -92,6 +92,7 @@ def baredoc(obj: object) -> str:
 
     Args:
         obj: any Python object.
+
     Returns:
         str: the first line of the docstring of obj.
     """

stagpy/field.py

@@ -80,9 +80,10 @@ def valid_field_var(var: str) -> bool:
 
     Args:
         var: the variable name to be checked.
+
     Returns:
-        whether the var is defined in `phyvars.FIELD` or
-        `phyvars.FIELD_EXTRA`.
+        whether the var is defined in either [`FIELD`][stagpy.phyvars.FIELD] or
+            [`FIELD_EXTRA`][stagpy.phyvars.FIELD_EXTRA].
     """
     return var in phyvars.FIELD or var in phyvars.FIELD_EXTRA
 
@@ -99,10 +100,12 @@ def get_meshes_fld(
         step: a `Step` of a `StagyyData` instance.
         var: scalar field name.
         walls: consider the walls as the relevant mesh.
+
     Returns:
-        tuple (xmesh, ymesh, fld, meta).  2D arrays containing respectively the
-        x position, y position, the values and the metadata of the requested
-        field.
+        xmesh: x position
+        ymesh: y position
+        fld: field values
+        meta: metadata
     """
     fld = step.fields[var]
     hwalls = (
@@ -139,10 +142,12 @@ def get_meshes_vec(
         conf: configuration.
         step: a `Step` of a `StagyyData` instance.
         var: vector field name.
+
     Returns:
-        tuple (xmesh, ymesh, fldx, fldy).  2D arrays containing respectively
-        the x position, y position, x component and y component of the
-        requested vector field.
+        xmesh: x position
+        ymesh: y position
+        fldx: x component
+        fldy: y component
     """
     if step.geom.threed and step.geom.cartesian:
         (xcoord, ycoord), (vec1, vec2) = _threed_extract(conf, step, var)
@@ -189,12 +194,12 @@ def plot_scalar(
             created.
         conf: configuration.
         extra: options that will be passed on to `matplotlib.axes.Axes.pcolormesh`.
+
     Returns:
-        fig, axis, surf, cbar
-            handles to various `matplotlib` objects, respectively the
-            figure, the axis, the surface returned by
-            `Axes.pcolormesh`, and the colorbar returned
-            by `matplotlib.pyplot.colorbar`.
+        fig: matplotlib figure
+        axes: matplotlib axes
+        surf: surface returned by `pcolormesh`
+        cbar: colorbar
     """
     if conf is None:
         conf = Config.default_()

stagpy/plates.py

@@ -50,9 +50,10 @@ def detect_plates(snap: Step, vz_thres_ratio: float = 0) -> tuple[NDArray, NDArr
             vertical velocities is performed.  Limits detected above a region
             where the vertical velocity is below `vz_thres_ratio * mean(vzabs)`
             are ignored.
+
     Returns:
-        tuple (itrenches, iridges).  1D arrays containing phi-index of detected
-        trenches and ridges.
+        itrenches: phi-indices of detected trenches
+        iridges: phi-indices of detected ridges
     """
     dvphi = _surf_diag(snap, "dv2").values
 

stagpy/processing.py

@@ -31,6 +31,7 @@ def dtime(sdat: StagyyData) -> Tseries:
 
     Args:
         sdat: a `StagyyData` instance.
+
     Returns:
         dt and time arrays.
     """
@@ -47,6 +48,7 @@ def dt_dt(sdat: StagyyData) -> Tseries:
 
     Args:
         sdat: a `StagyyData` instance.
+
     Returns:
         derivative of temperature and time arrays.
     """
@@ -65,6 +67,7 @@ def ebalance(sdat: StagyyData) -> Tseries:
 
     Args:
         sdat: a `StagyyData` instance.
+
     Returns:
         energy balance and time arrays.
     """
@@ -90,6 +93,7 @@ def mobility(sdat: StagyyData) -> Tseries:
 
     Args:
         sdat: a `StagyyData` instance.
+
     Returns:
         mobility and time arrays.
     """
@@ -108,6 +112,7 @@ def delta_r(step: Step) -> Rprof:
 
     Args:
         step: a `Step` of a `StagyyData` instance.
+
     Returns:
         the thickness of the cells and radius.
     """
@@ -131,6 +136,7 @@ def diff_prof(step: Step) -> Rprof:
 
     Args:
         step: a `Step` of a `StagyyData` instance.
+
     Returns:
         the diffusion and radius.
     """
@@ -153,6 +159,7 @@ def diffs_prof(step: Step) -> Rprof:
 
     Args:
         step: a `Step` of a `StagyyData` instance.
+
     Returns:
         the diffusion and radius.
     """
@@ -168,6 +175,7 @@ def advts_prof(step: Step) -> Rprof:
 
     Args:
         step: a `Step` of a `StagyyData` instance.
+
     Returns:
         the scaled advection and radius.
     """
@@ -185,6 +193,7 @@ def advds_prof(step: Step) -> Rprof:
 
     Args:
         step: a `Step` of a `StagyyData` instance.
+
     Returns:
         the scaled downward advection and radius.
     """
@@ -202,6 +211,7 @@ def advas_prof(step: Step) -> Rprof:
 
     Args:
         step: a `Step` of a `StagyyData` instance.
+
     Returns:
         the scaled upward advection and radius.
     """
@@ -219,6 +229,7 @@ def energy_prof(step: Step) -> Rprof:
 
     Args:
         step: a `Step` of a `StagyyData` instance.
+
     Returns:
         the energy flux and radius.
     """
@@ -239,6 +250,7 @@ def advth(step: Step) -> Rprof:
 
     Args:
         step: a `Step` of a `StagyyData` instance.
+
     Returns:
         the theoretical advection and radius.
     """
@@ -263,6 +275,7 @@ def init_c_overturn(step: Step) -> Rprof:
 
     Args:
         step: a `Step` of a `StagyyData` instance.
+
     Returns:
         the composition and radius.
     """
@@ -299,6 +312,7 @@ def c_overturned(step: Step) -> Rprof:
 
     Args:
         step: a `Step` of a `StagyyData` instance.
+
     Returns:
         the composition and radius.
     """
@@ -315,6 +329,7 @@ def stream_function(step: Step) -> Field:
 
     Args:
         step: a `Step` of a `StagyyData` instance.
+
     Returns:
         the stream function field.
     """

stagpy/stagyydata.py

@@ -2,9 +2,8 @@
 
 Note:
     The helper classes are not designed to be instantiated on their own, but
-    only as attributes of StagyyData instances. Users of this module should
-    only instantiate :class:`StagyyData`.
-
+    only as attributes of `StagyyData` instances. Users of this module should
+    only instantiate [`StagyyData`][stagpy.stagyydata.StagyyData].
 """
 
 from __future__ import annotations
@@ -784,6 +783,7 @@ def filename(
             timestep: snapshot number if relevant.
             suffix: optional suffix of file name.
             force_legacy: force returning the legacy output path.
+
         Returns:
             the path of the output file constructed with the provided segments.
         """
@@ -802,6 +802,7 @@ def _binfiles_set(self, isnap: int) -> set[Path]:
 
         Args:
             isnap: snapshot index.
+
         Returns:
             the set of output files available for this snapshot number.
         """

stagpy/time_series.py

@@ -105,9 +105,9 @@ def compstat(
         tstart: starting time. Set to None to start at the beginning of
             available data.
         tend: ending time. Set to None to stop at the end of available data.
+
     Returns:
-        a `pandas.DataFrame` with statistics. 'mean' and 'rms' as index,
-        variable names as columns.
+        statistics. `"mean"` and `"rms"` as index, variable names as columns.
     """
     stats = pd.DataFrame(columns=names, index=["mean", "rms"])
     for name in names: