Improve cross-references in docs

Author: amorison

docs/sources/stagyydata.rst

@@ -138,28 +138,49 @@ Geometry information are read from binary files.  :attr:`Step.geom
 <stagpy._step.Step.geom>` has various attributes defining the geometry of
 the problem.
 
-``cartesian``, ``curvilinear``, ``cylindrical``, ``spherical`` and ``yinyang``
-booleans define the shape of the domain (``curvilinear`` being the opposite of
-``cartesian``, ``True`` if ``cylindrical`` or ``spherical`` is ``True``).
-
-``twod_xz``, ``twod_yz``, ``twod`` and ``threed`` booleans indicate the number
-of spatial dimensions in the simulation. Note that fields are always four
+:attr:`~stagpy._step._Geometry.cartesian`,
+:attr:`~stagpy._step._Geometry.curvilinear`,
+:attr:`~stagpy._step._Geometry.cylindrical`,
+:attr:`~stagpy._step._Geometry.spherical` and
+:attr:`~stagpy._step._Geometry.yinyang` booleans define the shape of the domain
+(:attr:`~stagpy._step._Geometry.curvilinear` being the opposite of
+:attr:`~stagpy._step._Geometry.cartesian`, ``True`` if
+:attr:`~stagpy._step._Geometry.cylindrical` or
+:attr:`~stagpy._step._Geometry.spherical` is ``True``).
+
+:attr:`~stagpy._step._Geometry.twod_xz`,
+:attr:`~stagpy._step._Geometry.twod_yz`, :attr:`~stagpy._step._Geometry.twod`
+and :attr:`~stagpy._step._Geometry.threed` booleans indicate the number of
+spatial dimensions in the simulation. Note that fields are always four
 dimensional arrays (spatial + blocks) regardless of the actual dimension of the
 domain.
 
-``nxtot``, ``nytot``, ``nztot``, ``nbtot``, ``nttot``, ``nptot`` and ``nrtot``
-are the total number of points in the various spatial directions. Note that
-``nttot``, ``nptot`` and ``nrtot`` are the same as ``nxtot``, ``nytot`` and
-``nztot`` regardless of whether the geometry is cartesian or curvilinear.
-
-``x_centers``, ``y_centers``, and ``z_centers`` as well as ``t_centers``,
-``p_centers``, and ``r_centers`` are the coordinates of cell centers in the
-three directions.  As for the total number of points, they are the same
+:attr:`~stagpy._step._Geometry.nxtot`, :attr:`~stagpy._step._Geometry.nytot`,
+:attr:`~stagpy._step._Geometry.nztot`, :attr:`~stagpy._step._Geometry.nbtot`,
+:attr:`~stagpy._step._Geometry.nttot`, :attr:`~stagpy._step._Geometry.nptot`
+and :attr:`~stagpy._step._Geometry.nrtot` are the total number of points in the
+various spatial directions. Note that :attr:`~stagpy._step._Geometry.nttot`,
+:attr:`~stagpy._step._Geometry.nptot` and :attr:`~stagpy._step._Geometry.nrtot`
+are the same as :attr:`~stagpy._step._Geometry.nxtot`,
+:attr:`~stagpy._step._Geometry.nytot` and :attr:`~stagpy._step._Geometry.nztot`
+regardless of whether the geometry is cartesian or curvilinear.
+
+:attr:`~stagpy._step._Geometry.x_centers`,
+:attr:`~stagpy._step._Geometry.y_centers`, and
+:attr:`~stagpy._step._Geometry.z_centers` as well as
+:attr:`~stagpy._step._Geometry.t_centers`,
+:attr:`~stagpy._step._Geometry.p_centers`, and
+:attr:`~stagpy._step._Geometry.r_centers` are the coordinates of cell centers
+in the three directions.  As for the total number of points, they are the same
 regardless of the actual geometry.
 
-Similarly to ``*_centers`` attributes, ``x_walls``, ``y_walls``, and
-``z_walls`` as well as ``t_walls``, ``p_walls``, and ``r_walls`` are the
-coordinates of cell walls in the three directions.
+Similarly to ``*_centers`` attributes, :attr:`~stagpy._step._Geometry.x_walls`,
+:attr:`~stagpy._step._Geometry.y_walls`, and
+:attr:`~stagpy._step._Geometry.z_walls` as well as
+:attr:`~stagpy._step._Geometry.t_walls`,
+:attr:`~stagpy._step._Geometry.p_walls`, and
+:attr:`~stagpy._step._Geometry.r_walls` are the coordinates of cell walls in
+the three directions.
 
 Scalar and vector fields
 ------------------------

stagpy/_step.py

@@ -492,9 +492,9 @@ def bounds(self):
 class Step:
     """Time step data structure.
 
-    Elements of :class:`_Steps` and :class:`_Snaps` instances are all
-    :class:`Step` instances. Note that :class:`Step` objects are not
-    duplicated.
+    Elements of :class:`~stagpy.stagyydata._Steps` and
+    :class:`~stagpy.stagyydata._Snaps` instances are all :class:`Step`
+    instances. Note that :class:`Step` objects are not duplicated.
 
     Examples:
         Here are a few examples illustrating some properties of :class:`Step`

stagpy/field.py

@@ -57,7 +57,7 @@ def valid_field_var(var):
     """Whether a field variable is defined.
 
     This function checks if a definition of the variable exists in
-    :data:`phyvars.FIELD` or :data:`phyvars.FIELD_EXTRA`.
+    :data:`~stagpy.phyvars.FIELD` or :data:`~stagpy.phyvars.FIELD_EXTRA`.
 
     Args:
         var (str): the variable name to be checked.
@@ -73,8 +73,7 @@ def get_meshes_fld(step, var, walls=False):
     Only works properly in 2D geometry and 3D cartesian.
 
     Args:
-        step (:class:`~stagpy.stagyydata._Step`): a step of a StagyyData
-            instance.
+        step (:class:`~stagpy._step.Step`): a step of a StagyyData instance.
         var (str): scalar field name.
         walls (bool): consider the walls as the relevant mesh.
     Returns:
@@ -109,8 +108,7 @@ def get_meshes_vec(step, var):
     Only works properly in 2D geometry and 3D cartesian.
 
     Args:
-        step (:class:`~stagpy.stagyydata._Step`): a step of a StagyyData
-            instance.
+        step (:class:`~stagpy._step.Step`): a step of a StagyyData instance.
         var (str): vector field name.
     Returns:
         tuple of :class:`numpy.array`: xmesh, ymesh, fldx, fldy
@@ -146,8 +144,7 @@ def plot_scalar(step, var, field=None, axis=None, **extra):
     """Plot scalar field.
 
     Args:
-        step (:class:`~stagpy.stagyydata._Step`): a step of a StagyyData
-            instance.
+        step (:class:`~stagpy._step.Step`): a step of a StagyyData instance.
         var (str): the scalar field name.
         field (:class:`numpy.array`): if not None, it is plotted instead of
             step.fields[var].  This is useful to plot a masked or rescaled
@@ -252,8 +249,7 @@ def plot_iso(axis, step, var, **extra):
         axis (:class:`matplotlib.axes.Axes`): the axis handler of an
             existing matplotlib figure where the isocontours should
             be plotted.
-        step (:class:`~stagpy.stagyydata._Step`): a step of a StagyyData
-            instance.
+        step (:class:`~stagpy._step.Step`): a step of a StagyyData instance.
         var (str): the scalar field name.
         extra (dict): options that will be passed on to
             :func:`matplotlib.axes.Axes.contour`.
@@ -277,8 +273,7 @@ def plot_vec(axis, step, var):
         axis (:class:`matplotlib.axes.Axes`): the axis handler of an
             existing matplotlib figure where the vector field should
             be plotted.
-        step (:class:`~stagpy.stagyydata._Step`): a step of a StagyyData
-            instance.
+        step (:class:`~stagpy._step.Step`): a step of a StagyyData instance.
         var (str): the vector field name.
     """
     xmesh, ymesh, vec1, vec2 = get_meshes_vec(step, var)

stagpy/misc.py

@@ -121,15 +121,16 @@ def find_in_sorted_arr(value, array, after=False):
 class CachedReadOnlyProperty:
     """Descriptor implementation of read-only cached properties.
 
-    Properties are cached as _cropped_{name} instance attribute.
+    Properties are cached as ``_cropped_{name}`` instance attribute.
 
-    This is preferable to using a combination of property and
-    functools.lru_cache since the cache is bound to instances and therefore get
-    GCd with the instance when the latter is no longer in use instead of
-    staying in the cache which would use the instance itself as its key.
+    This is preferable to using a combination of ``@property`` and
+    ``@functools.lru_cache`` since the cache is bound to instances and
+    therefore get GCd with the instance when the latter is no longer in use
+    instead of staying in the cache which would use the instance itself as its
+    key.
 
-    This also has an advantage over @cached_property (Python>3.8): the property
-    is read-only instead of being writeable.
+    This also has an advantage over ``@cached_property`` (Python>3.8): the
+    property is read-only instead of being writeable.
     """
 
     def __init__(self, thunk):

stagpy/refstate.py

@@ -12,7 +12,8 @@ def plot_ref(sdat, var):
 
     Args:
         sdat (:class:`~stagpy.stagyydata.StagyyData`): a StagyyData instance.
-        var (str): refstate variable, a key of :data:`stagpy.phyvars.REFSTATE`.
+        var (str): refstate variable, a key of
+            :data:`~stagpy.phyvars.REFSTATE`.
     """
     fig, axis = plt.subplots()
     adbts = sdat.refstate.adiabats

stagpy/rprof.py

@@ -65,7 +65,7 @@ def plot_grid(step):
     The figure is call grid_N.pdf where N is replace by the step index.
 
     Args:
-        step (:class:`~stagpy.stagyydata._Step`): a step of a StagyyData
+        step (:class:`~stagpy._step.Step`): a step of a StagyyData
             instance.
     """
     drad, rad, _ = step.rprofs['dr']