[DOC] pvsystem.singlediode math rendering (#971)

* first pass at docstring cleanup

* missed a fraction

* Apply suggestions from code review

Co-authored-by: Cliff Hansen <[email protected]>

* fix spacing issue, add seealso links

* stickler

* reorder docstring sections

Co-authored-by: Cliff Hansen <[email protected]>

Author: kandersolar

pvlib/pvsystem.py

@@ -1958,60 +1958,61 @@ def sapm_effective_irradiance(poa_direct, poa_diffuse, airmass_absolute, aoi,
 def singlediode(photocurrent, saturation_current, resistance_series,
                 resistance_shunt, nNsVth, ivcurve_pnts=None,
                 method='lambertw'):
-    """
-    Solve the single-diode model to obtain a photovoltaic IV curve.
+    r"""
+    Solve the single-diode equation to obtain a photovoltaic IV curve.
 
-    Singlediode solves the single diode equation [1]_
+    Solves the single diode equation [1]_
 
     .. math::
 
-        I = IL - I0*[exp((V+I*Rs)/(nNsVth))-1] - (V + I*Rs)/Rsh
+        I = I_L -
+            I_0 \left[
+                \exp \left(\frac{V+I R_s}{n N_s V_{th}} \right)-1
+            \right] -
+            \frac{V + I R_s}{R_{sh}}
 
-    for ``I`` and ``V`` when given ``IL, I0, Rs, Rsh,`` and ``nNsVth
-    (nNsVth = n*Ns*Vth)`` which are described later. Returns a DataFrame
+    for :math:`I` and :math:`V` when given :math:`I_L, I_0, R_s, R_{sh},` and
+    :math:`n N_s V_{th}` which are described later. Returns a DataFrame
     which contains the 5 points on the I-V curve specified in
-    SAND2004-3535 [3]_. If all IL, I0, Rs, Rsh, and nNsVth are scalar, a
-    single curve will be returned, if any are Series (of the same
-    length), multiple IV curves will be calculated.
+    [3]_. If all :math:`I_L, I_0, R_s, R_{sh},` and
+    :math:`n N_s V_{th}` are scalar, a single curve is returned, if any
+    are Series (of the same length), multiple IV curves are calculated.
 
-    The input parameters can be calculated using calcparams_desoto from
-    meteorological data.
+    The input parameters can be calculated from meteorological data using a
+    function for a single diode model, e.g.,
+    :py:func:`~pvlib.pvsystem.calcparams_desoto`.
 
     Parameters
     ----------
     photocurrent : numeric
-        Light-generated current (photocurrent) in amperes under desired
-        IV curve conditions. Often abbreviated ``I_L``.
-        0 <= photocurrent
+        Light-generated current :math:`I_L` (photocurrent)
+        ``0 <= photocurrent``. [A]
 
     saturation_current : numeric
-        Diode saturation current in amperes under desired IV curve
-        conditions. Often abbreviated ``I_0``.
-        0 < saturation_current
+        Diode saturation :math:`I_0` current under desired IV curve
+        conditions. ``0 < saturation_current``. [A]
 
     resistance_series : numeric
-        Series resistance in ohms under desired IV curve conditions.
-        Often abbreviated ``Rs``.
-        0 <= resistance_series < numpy.inf
+        Series resistance :math:`R_s` under desired IV curve conditions.
+        ``0 <= resistance_series < numpy.inf``.  [ohm]
 
     resistance_shunt : numeric
-        Shunt resistance in ohms under desired IV curve conditions.
-        Often abbreviated ``Rsh``.
-        0 < resistance_shunt <= numpy.inf
+        Shunt resistance :math:`R_{sh}` under desired IV curve conditions.
+        ``0 < resistance_shunt <= numpy.inf``.  [ohm]
 
     nNsVth : numeric
-        The product of three components. 1) The usual diode ideal factor
-        (n), 2) the number of cells in series (Ns), and 3) the cell
-        thermal voltage under the desired IV curve conditions (Vth). The
-        thermal voltage of the cell (in volts) may be calculated as
-        ``k*temp_cell/q``, where k is Boltzmann's constant (J/K),
-        temp_cell is the temperature of the p-n junction in Kelvin, and
-        q is the charge of an electron (coulombs).
-        0 < nNsVth
+        The product of three components: 1) the usual diode ideality factor
+        :math:`n`, 2) the number of cells in series :math:`N_s`, and 3)
+        the cell thermal voltage
+        :math:`V_{th}`. The thermal voltage of the cell (in volts) may be
+        calculated as :math:`k_B T_c / q`, where :math:`k_B` is
+        Boltzmann's constant (J/K), :math:`T_c` is the temperature of the p-n
+        junction in Kelvin, and :math:`q` is the charge of an electron
+        (coulombs). ``0 < nNsVth``.  [V]
 
     ivcurve_pnts : None or int, default None
-        Number of points in the desired IV curve. If None or 0, no
-        IV curves will be produced.
+        Number of points in the desired IV curve. If None or 0, no points on
+        the IV curves will be produced.
 
     method : str, default 'lambertw'
         Determines the method used to calculate points on the IV curve. The
@@ -2043,6 +2044,14 @@ def singlediode(photocurrent, saturation_current, resistance_series,
     The output will be a DataFrame if photocurrent is a Series and
     ivcurve_pnts is None.
 
+    See also
+    --------
+    calcparams_desoto
+    calcparams_cec
+    calcparams_pvsyst
+    sapm
+    pvlib.singlediode.bishop88
+
     Notes
     -----
     If the method is ``'lambertw'`` then the solution employed to solve the
@@ -2079,12 +2088,6 @@ def singlediode(photocurrent, saturation_current, resistance_series,
     .. [4] "Computer simulation of the effects of electrical mismatches in
        photovoltaic cell interconnection circuits" JW Bishop, Solar Cell (1988)
        https://doi.org/10.1016/0379-6787(88)90059-2
-
-    See also
-    --------
-    sapm
-    calcparams_desoto
-    pvlib.singlediode.bishop88
     """
     # Calculate points on the IV curve using the LambertW solution to the
     # single diode equation