docs: add docstrings to a few attributes

Author: amorison

stagpy/config.py

@@ -1,6 +1,6 @@
 """Define configuration variables for StagPy.
 
-See :mod:`stagpy.args` for additional definitions related to the command line
+See [stagpy.args][] for additional definitions related to the command line
 interface.
 """
 
@@ -21,6 +21,7 @@
 )
 
 CONFIG_LOCAL = Path(".stagpy.toml")
+"""Path of local configuration file."""
 
 
 @dataclass

stagpy/datatypes.py

@@ -11,60 +11,67 @@
 
 @dataclass(frozen=True)
 class Varf:
-    """Metadata of scalar field.
-
-    `dim` is the dimension used to scale to dimensional values.
-    """
+    """Metadata of scalar field."""
 
     description: str
+    """description of field variable."""
     dim: str
+    """dimension used to scale to dimensional values."""
 
 
 @dataclass(frozen=True)
 class Field:
     """Scalar field and associated metadata."""
 
     values: NDArray
+    """values of field."""
     meta: Varf
+    """metadata."""
 
 
 @dataclass(frozen=True)
 class Varr:
-    """Metadata of radial profiles.
-
-    `dim` is the dimension used to scale to dimensional values.
-    """
+    """Metadata of radial profiles."""
 
     description: str
+    """description of profile variable."""
     kind: str
+    """short description"""
     dim: str
+    """dimension used to scale to dimensional values."""
 
 
 @dataclass(frozen=True)
 class Rprof:
     """Radial profile with associated radius and metadata."""
 
     values: NDArray
+    """values of profile."""
     rad: NDArray
+    """radial position of profile."""
     meta: Varr
+    """metadata."""
 
 
 @dataclass(frozen=True)
 class Vart:
-    """Metadata of time series.
-
-    `dim` is the dimension used to scale to dimensional values.
-    """
+    """Metadata of time series."""
 
     description: str
+    """description of time series."""
     kind: str
+    """short description"""
     dim: str
+    """dimension used to scale to dimensional values."""
 
 
 @dataclass(frozen=True)
 class Tseries:
     """A time series with associated time and metadata."""
 
     values: NDArray
+    """values of time series."""
     time: NDArray
+    """time position of time series."""
     meta: Vart
+    """metadata."""

stagpy/phyvars.py

@@ -1,7 +1,7 @@
 """Lists of physical variables made available by StagPy.
 
 They are organized by kind of variables (field, profiles, and time series).
-EXTRA lists group variables that are not directly output by StagYY and need to
+`EXTRA` lists group variables that are not directly output by StagYY and need to
 be computed from other variables.
 """
 
@@ -66,12 +66,14 @@
         "fFeR": Varf("fFeR", "1"),
     }
 )
+"""Scalar fields output by StagYY."""
 
 FIELD_EXTRA: Mapping[str, Callable[[Step], Field]] = MappingProxyType(
     {
         "stream": processing.stream_function,
     }
 )
+"""Scalar fields that StagPy can compute."""
 
 FIELD_FILES: Mapping[str, list[str]] = MappingProxyType(
     {
@@ -156,6 +158,7 @@
         "crust": Varf("Crustal thickness", "m"),
     }
 )
+"""Surface scalar fields output by StagYY."""
 
 SFIELD_FILES: Mapping[str, list[str]] = MappingProxyType(
     {
@@ -255,6 +258,7 @@
         "advasc": Varr("Upward advection", "Heat flux", "W/m2"),
     }
 )
+"""Radial profiles output by StagYY."""
 
 RPROF_EXTRA: Mapping[str, Callable[[Step], Rprof]] = MappingProxyType(
     {
@@ -270,6 +274,7 @@
         "advth": processing.advth,
     }
 )
+"""Radial profiles that StagPy can compute."""
 
 
 TIME: Mapping[str, Vart] = MappingProxyType(
@@ -305,6 +310,7 @@
         "botT_val": Vart("Temperature at bottom", "Temperature", "K"),
     }
 )
+"""Time series output by StagYY."""
 
 TIME_EXTRA: Mapping[str, Callable[[StagyyData], Tseries]] = MappingProxyType(
     {
@@ -314,6 +320,7 @@
         "mobility": processing.mobility,
     }
 )
+"""Time series that StagPy can compute."""
 
 REFSTATE: Mapping[str, Varr] = MappingProxyType(
     {
@@ -327,6 +334,7 @@
         "grav": Varr("Gravity", "Gravity", "m/s2"),
     }
 )
+"""Variables in [`Refstate`][stagpy.stagyydata.Refstate]."""
 
 SCALES: Mapping[str, Callable[[Scales], float]] = MappingProxyType(
     {
@@ -346,5 +354,6 @@
         "m/s2": attrgetter("acceleration"),
     }
 )
+"""Scales to make values dimensional, see [`Scales`][stagpy.dimensions.Scales]."""
 
 PREFIXES = ("k", "M", "G")