Docs: Fix a bunch more unrecognised types in docstrings

freegs/critical.py

@@ -58,13 +58,10 @@ def find_critical(R, Z, psi, discard_xpoints=True):
 
     Returns
     -------
-    opoint, xpoint:
-        Two lists of critical points.
-
-        Each of these is a list of tuples with (R, Z, psi) points
-
-        The first tuple is the primary O-point (magnetic axis)
-        and primary X-point (separatrix)
+    opoint: list
+        List of O-points (magnetic axes) consisting of ``(R, Z, psi)`` tuples
+    xpoint: list
+        List of X-points (magnetic axes) consisting of ``(R, Z, psi)`` tuples
 
     """
 
@@ -255,7 +252,7 @@ def core_mask(R, Z, psi, opoint, xpoint=[], psi_bndry=None):
 
     Returns
     -------
-    array:
+    numpy.ndarray
         A 2D array [nx,ny] which is 1 inside the core, 0 outside
 
     """

freegs/dump.py

@@ -108,7 +108,7 @@ def __enter__(self):
     def __exit__(self, type, value, traceback):
         self.close()
 
-    def write_equilibrium(self, equilibrium):
+    def write_equilibrium(self, equilibrium: Equilibrium):
         """
         Write ``equilbrium`` to file
         """
@@ -181,14 +181,9 @@ def write_equilibrium(self, equilibrium):
             # type to restore it to later
             coils_group[label].attrs["freegs type"] = coil.__class__.__name__
 
-    def read_equilibrium(self):
+    def read_equilibrium(self) -> Equilibrium:
         """
         Read an equilibrium from the file
-
-        Returns
-        -------
-        Equilibrium
-            A new `Equilibrium` object
         """
 
         equilibrium_group = self.handle[self.EQUILIBRIUM_GROUP_NAME]

freegs/equilibrium.py

@@ -199,8 +199,8 @@ def callSolver(self, psi, rhs):
 
         Returns
         -------
-
-        Solution psi
+        float:
+            Solution psi
 
         """
         return self._solver(psi, rhs)
@@ -455,18 +455,19 @@ def solve(self, profiles, Jtor=None, psi=None, psi_bndry=None):
             An object describing the plasma profiles.
             At minimum this must have methods:
 
-            - `.Jtor(R, Z, psi, psi_bndry) -> [nx, ny]`
-            - `.pprime(psinorm)`
-            - `.ffprime(psinorm)`
-            - `.pressure(psinorm)`
-            - `.fpol(psinorm)`
+            - ``.Jtor(R, Z, psi, psi_bndry) -> [nx, ny]``
+            - ``.pprime(psinorm)``
+            - ``.ffprime(psinorm)``
+            - ``.pressure(psinorm)``
+            - ``.fpol(psinorm)``
 
-        Jtor : 2D array
-            If supplied, specifies the toroidal current at each (R,Z) point
-            If not supplied, Jtor is calculated from profiles by finding O,X-points
+        Jtor :
+            If supplied, a 2D array specifying the toroidal current at each
+            (R,Z) point.  If not supplied, Jtor is calculated from profiles by
+            finding O,X-points
         psi_bndry:
-            Poloidal flux to use as the separatrix (plasma
-            boundary). If not given then X-point locations are used.
+            Poloidal flux to use as the separatrix (plasma boundary). If not
+            given then X-point locations are used.
         """
 
         self._profiles = profiles

freegs/fieldtracer.py

@@ -148,9 +148,15 @@ def follow(self, Rstart, Zstart, angles, rtol=None, backward=False):
 
 class LineCoordinates:
     """Coordinates of a field line
-    R   Major radius [m]
-    Z   Height [m]
-    length   Field line length [m]
+
+    Attributes
+    ----------
+    R:
+        Major radius [m]
+    Z:
+        Height [m]
+    length:
+        Field line length [m]
 
     All {R, Z, length} are NumPy arrays of the same shape
     """
@@ -181,14 +187,15 @@ def traceFieldLines(eq, solwidth=0.03, nlines=10, nturns=50, npoints=200, axis=N
 
     Returns
     -------
-    [LineCoordinates, LineCoordinates]:
-        The forward and backward field line coordinates
-        stored in LineCoordinates objects
+    forward: LineCoordinates
+        The forward field line coordinates
+    backward: LineCoordinates
+        The backward field line coordinates
 
-        >>> forward, backward = traceFieldLines(eq)
+    Example
+    -------
 
-        forward and backward have data members
-        R, Z, length  2D arrays of shape (npoints, nlines)
+        >>> forward, backward = traceFieldLines(eq)
 
     """
     ft = FieldTracer(eq)

freegs/geqdsk.py

@@ -175,10 +175,12 @@ def read(
     fit_sol: bool=False,
     maxits: int=50,
     current_bounds: Optional[list]=None,
-):
+) -> Equilibrium:
     """
     Reads a G-EQDSK format file
 
+    A nonlinear solve will be performed, using Picard iteration
+
     Parameters
     ----------
     fh :
@@ -200,14 +202,13 @@ def read(
         COordinate COnventions. Not fully handled yet,
         only whether psi is divided by 2pi or not.
         if < 10 then psi is divided by 2pi, otherwise not.
-    domain : list/tuple of 4 elements
-        Sets the (R,Z) domain to solve for
-        (Rmin, Rmax, Zmin, Zmax)
-    blend : float between 0 and 1
+    domain :
+        Sets the (R,Z) domain to solve for ``(Rmin, Rmax, Zmin, Zmax)``
+    blend :
         Weighting of the previous poloidal flux at each step of the
         Picard iteration. The default (0.0) is to use no blending.
         Blending slows convergence, but can stabilise some oscillating
-        unstable solutions.
+        unstable solutions. Must be in ``[0, 1]``
     fit_sol :
         If False (default) then only the poloidal flux inside the
         separatrix is used to constrain the coil currents.
@@ -218,17 +219,15 @@ def read(
     maxits :
         Maximum number of iterations. Set to None for no limit.
         If this limit is exceeded then a RuntimeError is raised.
-    current_bounds: List of tuples
+    current_bounds:
         Optional list of tuples representing constraints on coil currents to be used
         when reconstructing the equilibrium from the geqdsk file.
         ``[(l1,u1),(l2,u2)...(lN,uN)]``
 
-    A nonlinear solve will be performed, using Picard iteration
-
     Returns
     -------
-    Equilibrium:
-        An Equilibrium object eq. In addition, the following is available:
+    eq: ~.Equilibrium
+        An :class:`~.Equilibrium` object. In addition, the following is available:
 
         - eq.control   - The control system
         - eq._profiles - The profiles object

freegs/multigrid.py

@@ -175,8 +175,8 @@ def restrict(orig, out=None, avg=False):
 
     Returns
     -------
-
-    A 2D numpy array of size [(nx-1)/2+1, (ny-1)/2+1]
+    numpy.ndarray
+        A 2D numpy array of size [(nx-1)/2+1, (ny-1)/2+1]
     """
 
     nx = orig.shape[0]

freegs/optimise.py

@@ -177,10 +177,10 @@ def optimise(eq, controls, measure, maxgen=10, N=10, CR=0.3, F=1.0, monitor=None
         Maximum number of generations
     N:
         Population size (must be >= 4)
-    CR: [0,1]
-        Crossover probability
-    F:  [0,2] 
-        Differential weight
+    CR:
+        Crossover probability (must be in ``[0,1]``)
+    F:
+        Differential weight (must be in ``[0,2]``)
     monitor(generation, best, population):
         A function to be called each generation with the best
         Equilibrium and the whole population
@@ -191,7 +191,8 @@ def optimise(eq, controls, measure, maxgen=10, N=10, CR=0.3, F=1.0, monitor=None
 
     Returns
     -------
-    The `Equilibrium` with the lowest measure (score).
+    ~.Equilibrium:
+        The :class:`~.Equilibrium` with the lowest measure (score).
 
     """
 

freegs/optimiser.py

@@ -99,10 +99,10 @@ def optimise(obj, controls, measure, maxgen=10, N=10, CR=0.3, F=1.0, monitor=Non
         Maximum number of generations
     N:
         Population size (must be >= 4)
-    CR: [0,1]
-        Crossover probability
-    F:  [0,2] 
-        Differential weight
+    CR:
+        Crossover probability (must be in ``[0,1]``)
+    F:
+        Differential weight (must be in ``[0,2]``)
     monitor(generation, best, population):
         A function to be called each generation with the best
         Equilibrium and the whole population
@@ -113,7 +113,8 @@ def optimise(obj, controls, measure, maxgen=10, N=10, CR=0.3, F=1.0, monitor=Non
 
     Returns
     -------
-    The `Equilibrium` with the lowest measure (score).
+    ~.Equilibrium:
+        The :class:`~.Equilibrium` with the lowest measure (score).
 
     """