Add pvlib.spa.transit_sunrise_sunset to documentation

docs/sphinx/source/reference/solarposition.rst

@@ -41,6 +41,7 @@ Functions for calculating sunrise, sunset and transit times.
    solarposition.sun_rise_set_transit_ephem
    solarposition.sun_rise_set_transit_spa
    solarposition.sun_rise_set_transit_geometric
+   spa.transit_sunrise_sunset
 
 
 The spa module contains the implementation of the built-in NREL SPA

docs/sphinx/source/whatsnew/v0.16.2.rst

@@ -31,13 +31,14 @@ Enhancements
 
 Documentation
 ~~~~~~~~~~~~~
+* Add :py:func:`pvlib.spa.transit_sunrise_sunset` to the API reference.
+  (:issue:`2255`, :pull:`2873`)
 * Clarified in :py:func:`pvlib.tracking.singleaxis` that the tracker
   rotation minimizes the angle of incidence (AOI) to maximize the use of
   direct normal irradiance (DNI). (:issue:`2314`, :pull:`2869`)
 * Fix the :py:func:`pvlib.spa.solar_position` docstring, which listed
   outputs ``elevation`` and ``apparent_elevation`` in the wrong order.
   (:issue:`2886`, :pull:`2887`)
-
 * Clarify that :py:func:`pvlib.ivtools.sdm.fit_pvsyst_sandia` and
   :py:func:`pvlib.ivtools.sdm.fit_desoto_sandia` require multiple IV curves.
   (:issue:`1715`, :pull:`2883`)

pvlib/spa.py

@@ -1109,7 +1109,9 @@ def solar_position(unixtime, lat, lon, elev, pressure, temp, delta_t,
 def transit_sunrise_sunset(dates, lat, lon, delta_t, numthreads):
     """
     Calculate the sun transit, sunrise, and sunset
-    for a set of dates at a given location.
+    for a set of dates at a given location using the NREL SPA.
+
+    The NREL SPA is documented in [1]_, [2]_.
 
     Parameters
     ----------
@@ -1130,7 +1132,16 @@ def transit_sunrise_sunset(dates, lat, lon, delta_t, numthreads):
     -------
     tuple : (transit, sunrise, sunset) localized to UTC
 
-    """
+    References
+    ----------
+    .. [1] I. Reda and A. Andreas, Solar position algorithm for solar
+       radiation applications. Solar Energy, vol. 76, no. 5, pp. 577-589,
+       2004. :doi:`10.1016/j.solener.2003.12.003`
+    .. [2] I. Reda, and A. Andreas. "Corrigendum to “Solar position
+       algorithm for solar radiation applications." [Solar Energy 76
+       (2004) 577–589] Solar Energy, vol. 81,  no. 6, pp. 838, 2007.
+       :doi:`10.1016/j.solener.2007.01.003`
+   """
 
     if ((dates % 86400) != 0.0).any():
         raise ValueError('Input dates must be at 00:00 UTC')