DOC: add reference callouts and enable footnote warnings

docs/examples/adr-pvarray/plot_fit_to_matrix.py

@@ -12,6 +12,8 @@
 parameters can be determined with just a few lines of code using
 functions in pvlib-python.
 
+The ADR efficiency model is described in [1]_ and [2]_.
+
 Author: Anton Driesse
 """
 

docs/examples/adr-pvarray/plot_simulate_fast.py

@@ -13,6 +13,8 @@
 
 To compare simulation speed, we run them using ``timeit``.
 
+The ADR efficiency model is described in [1]_ and [2]_.
+
 Author: Anton Driesse
 """
 

docs/examples/adr-pvarray/plot_simulate_system.py

@@ -9,6 +9,8 @@
 Efficiency is independent of system size, so adjusting the system
 capacity is just a matter of setting the desired value, e.g. P_STC = 5000.
 
+The ADR efficiency model is described in [1]_ and [2]_.
+
 Author: Anton Driesse
 """
 

docs/examples/reflections/plot_convert_iam_models.py

@@ -17,8 +17,9 @@
 #
 # Here, we show how to use
 # :py:func:`~pvlib.iam.convert` to estimate parameters for a desired target
-# IAM model from a source IAM model. Model conversion uses a weight
-# function that can assign more influence to some AOI values than others.
+# IAM model from a source IAM model using the method in [1]_.
+# Model conversion uses a weight function that can assign more influence to
+# some AOI values than others.
 # We illustrate how to provide a custom weight function to
 # :py:func:`~pvlib.iam.convert`.
 

docs/sphinx/source/conf.py

@@ -380,10 +380,6 @@ def setup(app):
 
 ipython_warning_is_error = False
 
-# suppress "WARNING: Footnote [1] is not referenced." messages
-# https://github.com/pvlib/pvlib-python/issues/837
-suppress_warnings = ['ref.footnote']
-
 os_re_sep = re.escape(os.path.sep)
 # settings for sphinx-gallery
 sphinx_gallery_conf = {

docs/sphinx/source/user_guide/modeling_topics/spectrum.rst

@@ -23,6 +23,7 @@ given spectrum to its response under a reference spectrum, typically the
 AM1.5G spectrum. It represents the relative difference in the performance of
 a PV device under a spectrum different from the reference spectrum, and can be
 used to correct the measured power output of a PV system for spectral effects.
+The spectral mismatch correction for device measurements is standardized in [9]_.
 
 pvlib-python contains several models to estimate the spectral mismatch factor
 using atmospheric variables such as air mass, or calculate it exactly using
@@ -49,16 +50,16 @@ Reference [2]_.
 +=====================================================+=============================+=========+=========+======+======+======+============+===========+
 | :py:func:`Caballero <spectral_factor_caballero>`    | :term:`airmass_absolute`,   |         |         |      |      |      |            |           |
 |                                                     +-----------------------------+         |         |      |      |      |            |           |
-|                                                     |:term:`precipitable_water`,  |   ✓     |    ✓    |  ✓   |   ✓  |  ✓   |     ✓      |   [2]_    |
+|                                                     |:term:`precipitable_water`,  |   ✓     |    ✓    |  ✓   |   ✓  |  ✓   |     ✓      |   [3]_    |
 |                                                     +-----------------------------+         |         |      |      |      |            |           |
 |                                                     | :term:`aod`                 |         |         |      |      |      |            |           |
 +-----------------------------------------------------+-----------------------------+---------+---------+------+------+------+------------+-----------+
 | :py:func:`First Solar <spectral_factor_firstsolar>` | :term:`airmass_absolute`,   |         |         |      |      |      |            |           |
-|                                                     +-----------------------------+         |    ✓    |  ✓   |      |      |            |   [3]_    |
+|                                                     +-----------------------------+         |    ✓    |  ✓   |      |      |            |   [7]_    |
 |                                                     | :term:`precipitable_water`  |         |         |      |      |      |            |           |
 +-----------------------------------------------------+-----------------------------+---------+---------+------+------+------+------------+-----------+
 | :py:func:`JRC <spectral_factor_jrc>`                | :term:`airmass_relative`,   |         |         |      |      |      |            |           |
-|                                                     +-----------------------------+         |    ✓    |  ✓   |      |      |            +   [4]_    |
+|                                                     +-----------------------------+         |    ✓    |  ✓   |      |      |            +   [8]_    |
 |                                                     | :term:`clearsky_index`      |         |         |      |      |      |            |           |
 +-----------------------------------------------------+-----------------------------+---------+---------+------+------+------+------------+-----------+
 | :py:func:`Polo <spectral_factor_polo>`              | :term:`precipitable_water`, |         |         |      |      |      |            |           |
@@ -72,10 +73,10 @@ Reference [2]_.
 |                                                     | :term:`pressure`            |         |         |      |      |      |            |           |
 +-----------------------------------------------------+-----------------------------+---------+---------+------+------+------+------------+-----------+
 | :py:func:`PVSPEC <spectral_factor_pvspec>`          | :term:`airmass_absolute`,   |         |         |      |      |      |            |           |
-|                                                     +-----------------------------+   ✓     |    ✓    |  ✓   |  ✓   |  ✓   |            |   [6]_    |
+|                                                     +-----------------------------+   ✓     |    ✓    |  ✓   |  ✓   |  ✓   |            |   [4]_    |
 |                                                     | clearsky_index              |         |         |      |      |      |            |           |
 +-----------------------------------------------------+-----------------------------+---------+---------+------+------+------+------------+-----------+
-| :py:func:`SAPM <spectral_factor_sapm>`              | :term:`airmass_absolute`    |         |         |      |      |      |            |   [7]_    |
+| :py:func:`SAPM <spectral_factor_sapm>`              | :term:`airmass_absolute`    |         |         |      |      |      |            |   [6]_    |
 +-----------------------------------------------------+-----------------------------+---------+---------+------+------+------+------------+-----------+
 
 

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

@@ -31,6 +31,9 @@ Enhancements
 
 Documentation
 ~~~~~~~~~~~~~
+* Add missing reference callouts in docstrings and documentation, correct
+  spectral model citations, and enable Sphinx warnings for unreferenced
+  footnotes. (:issue:`837`)
 * 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
@@ -78,3 +81,4 @@ Contributors
 * :ghuser:`bfs2021`
 * :ghuser:`xiajiahang`
 * Jakub Krasuski (:ghuser:`Blizzeq`)
+* :ghuser:`WhatIsAPM1989`

pvlib/atmosphere.py

@@ -29,7 +29,7 @@ def pres2alt(pressure):
 
     Notes
     ------
-    The following assumptions are made
+    The following assumptions are made in the derivation in [1]_
 
     ============================   ================
     Parameter                      Value
@@ -69,7 +69,7 @@ def alt2pres(altitude):
 
     Notes
     ------
-    The following assumptions are made
+    The following assumptions are made in the derivation in [1]_
 
     ============================   ================
     Parameter                      Value
@@ -98,7 +98,7 @@ def get_absolute_airmass(airmass_relative, pressure=101325.):
     Determine absolute (pressure-adjusted) airmass from relative
     airmass and pressure.
 
-    The calculation for absolute airmass (:math:`AM_a`) is
+    The calculation for absolute airmass (:math:`AM_a`) is given by [1]_
 
     .. math::
         AM_a = AM_r \frac{P}{101325}
@@ -267,7 +267,8 @@ def gueymard94_pw(temp_air, relative_humidity):
     accuracy of this method is approximately 20% for moderate PW (1-3
     cm) and less accurate otherwise.
 
-    The model was developed by expanding Eq. 1 in [2]_:
+    The model is described in [1]_ and was developed by expanding Eq. 1
+    in [2]_:
 
     .. math::
 
@@ -439,7 +440,7 @@ def bird_hulstrom80_aod_bb(aod380, aod500):
     Approximate broadband aerosol optical depth.
 
     Bird and Hulstrom developed a correlation for broadband aerosol optical
-    depth (AOD) using two wavelengths, 380 nm and 500 nm.
+    depth (AOD) using two wavelengths, 380 nm and 500 nm [1]_ [2]_.
 
     Parameters
     ----------
@@ -473,10 +474,14 @@ def bird_hulstrom80_aod_bb(aod380, aod500):
 
 def kasten96_lt(airmass_absolute, precipitable_water, aod_bb):
     """
-    Calculate Linke turbidity  using Kasten pyrheliometric formula.
+    Calculate Linke turbidity using the Kasten pyrheliometric formula.
+
+    The Linke turbidity factor [1]_ is calculated using the Kasten
+    formulations [2]_ [3]_ and the conversion in [5]_. An airmass-independent
+    formulation is discussed in [6]_.
 
     Note that broadband aerosol optical depth (AOD) can be approximated by AOD
-    measured at 700 nm according to Molineaux [4] . Bird and Hulstrom offer an
+    measured at 700 nm according to Molineaux [4]_. Bird and Hulstrom offer an
     alternate approximation using AOD measured at 380 nm and 500 nm.
 
     Based on original implementation by Armel Oumbe.
@@ -563,6 +568,8 @@ def angstrom_aod_at_lambda(aod0, lambda0, alpha=1.14, lambda1=700.0):
     r"""
     Get AOD at specified wavelength using Angstrom turbidity model.
 
+    The model is described in [1]_ and [2]_.
+
     Parameters
     ----------
     aod0 : numeric

pvlib/bifacial/ants2d.py

@@ -51,6 +51,10 @@ def _shaded_fraction(tracker_rotation, phi, gcr, x0=0, x1=1):
         Fraction of row slant height from the bottom that is shaded from
         direct irradiance.
 
+    Notes
+    -----
+    The shading geometry is described in [1]_.
+
     References
     ----------
     .. [1] Kevin Anderson and Mark Mikofski, "Slope-Aware Backtracking for
@@ -95,6 +99,8 @@ def _ants2d_singleside(tracker_rotation, cos_aoi, phi, gcr, height, pitch,
     Calculate plane-of-array irradiance components on one side of a row
     of modules.
 
+    The view factor model is described in [1]_.
+
     Parameters
     ----------
     tracker_rotation : numeric

pvlib/bifacial/infinite_sheds.py

@@ -112,7 +112,7 @@ def _shaded_fraction(solar_zenith, solar_azimuth, surface_tilt,
     Calculate fraction (from the bottom) of row slant height that is shaded
     from direct irradiance by the row in front toward the sun.
 
-    See [1], Eq. 14 and also [2], Eq. 32.
+    See [1]_, Eq. 14 and also [2]_, Eq. 32.
 
     .. math::
         F_x = \\max \\left( 0, \\min \\left(\\frac{\\text{GCR} \\cos \\theta
@@ -173,7 +173,7 @@ def get_irradiance_poa(surface_tilt, surface_azimuth, solar_zenith,
     r"""
     Calculate plane-of-array (POA) irradiance on one side of a row of modules.
 
-    The infinite sheds model [1] assumes the PV system comprises parallel,
+    The infinite sheds model [1]_ assumes the PV system comprises parallel,
     evenly spaced rows on a level, horizontal surface. Rows can be on fixed
     racking or single axis trackers. The model calculates irradiance at a
     location far from the ends of any rows, in effect, assuming that the
@@ -381,7 +381,7 @@ def get_irradiance(surface_tilt, surface_azimuth, solar_zenith, solar_azimuth,
     """
     Get front and rear irradiance using the infinite sheds model.
 
-    The infinite sheds model [1] assumes the PV system comprises parallel,
+    The infinite sheds model [1]_ assumes the PV system comprises parallel,
     evenly spaced rows on a level, horizontal surface. Rows can be on fixed
     racking or single axis trackers. The model calculates irradiance at a
     location far from the ends of any rows, in effect, assuming that the

pvlib/bifacial/utils.py

@@ -85,6 +85,10 @@ def _unshaded_ground_fraction(tracker_rotation, phi, gcr, height=None,
         Fraction of distance betwen rows (pitch) with direct irradiance
         (unshaded). [unitless]
 
+    Notes
+    -----
+    The geometry and derivation are described in [1]_.
+
     References
     ----------
     .. [1] K. S. Anderson, A. R. Jensen, and C. W. Hansen, "A Bifacial View
@@ -291,6 +295,10 @@ def vf_ground_sky_2d_integ(tracker_rotation, gcr, height, pitch, max_rows=10,
         Integration of view factor over the length between adjacent, interior
         rows.  Shape matches that of ``tracker_rotation``. [unitless]
 
+    Notes
+    -----
+    The geometry and derivation are described in [1]_.
+
     References
     ----------
     .. [1] K. S. Anderson, A. R. Jensen, and C. W. Hansen, "A Bifacial View
@@ -454,6 +462,10 @@ def vf_row_sky_2d_integ(surface_tilt, gcr, x0=0, x1=1):
         Average fraction of the sky dome visible from points in the segment
         from x0 to x1. [unitless]
 
+    Notes
+    -----
+    The geometry and derivation are described in [1]_.
+
     References
     ----------
     .. [1] K. S. Anderson, A. R. Jensen, and C. W. Hansen, "A Bifacial View
@@ -567,6 +579,10 @@ def vf_row_ground_2d_integ(surface_tilt, gcr, height=None, pitch=None,
         Integrated view factor to the visible ground on the interval (x0, x1).
         [unitless]
 
+    Notes
+    -----
+    The geometry and derivation are described in [1]_.
+
     References
     ----------
     .. [1] K. S. Anderson, A. R. Jensen, and C. W. Hansen, "A Bifacial View

pvlib/clearsky.py

@@ -283,10 +283,10 @@ def haurwitz(apparent_zenith):
     Determine clear sky GHI using the Haurwitz model.
 
     Implements the Haurwitz clear sky model for global horizontal
-    irradiance (GHI) as presented in [1, 2]. A report on clear
+    irradiance (GHI) as presented in [1]_ [2]_. A report on clear
     sky models found the Haurwitz model to have the best performance
     in terms of average monthly error among models which require only
-    zenith angle [3].
+    zenith angle [3]_.
 
     Parameters
     ----------
@@ -637,8 +637,9 @@ def _clear_sample_index(clear_windows, samples_per_window, align, H):
 
 def _clearsky_get_threshold(sample_interval):
     """
-    Returns threshold values for kwargs in detect_clearsky. See
-    Table 1 in [1].
+    Returns threshold values for kwargs in detect_clearsky.
+
+    See Table 1 in [1]_.
 
     References
     ----------
@@ -930,7 +931,9 @@ def bird(zenith, airmass_relative, aod380, aod500, precipitable_water,
     """
     Bird Simple Clear Sky Broadband Solar Radiation Model
 
-    Based on NLR Excel implementation by Daryl R. Myers [1, 2].
+    Based on the NLR Excel implementation [3]_ by Daryl R. Myers [2]_
+    of the Bird and Hulstrom model [1]_ [4]_. Corrections to the model
+    are documented in the error reports [5]_.
 
     Bird and Hulstrom define the zenith as the "angle between a line to
     the sun and the local zenith". There is no distinction in the paper

pvlib/iam.py

@@ -103,7 +103,7 @@ def physical(aoi, n=1.526, K=4.0, L=0.002, *, n_ar=None):
     ``iam.physical`` calculates the incidence angle modifier as described in
     [1]_, Section 3, with additional support of an anti-reflective coating.
     The calculation is based on a physical model of reflections, absorption,
-    and transmission through a transparent cover.
+    and transmission through a transparent cover, as described in [2]_.
 
     Parameters
     ----------
@@ -117,7 +117,7 @@ def physical(aoi, n=1.526, K=4.0, L=0.002, *, n_ar=None):
 
     K : numeric, default 4.0
         The glazing extinction coefficient in units of 1/meters.
-        Reference [1] indicates that a value of 4 is reasonable for
+        Reference [1]_ indicates that a value of 4 is reasonable for
         "water white" glass.
 
     L : numeric, default 0.002
@@ -319,8 +319,9 @@ def martin_ruiz_diffuse(surface_tilt, a_r=0.16, c1=0.4244, c2=None):
     Determine the incidence angle modifiers (IAM) for sky diffuse and
     ground-reflected irradiance using the Martin and Ruiz incident angle model.
 
-    As described in [1]_, the IAMs result from integrals that assume the
-    incoming sky diffuse and ground-reflected irradiance are isotropic.
+    As described in [1]_ and corrected in [2]_, the IAMs result from integrals
+    that assume the incoming sky diffuse and ground-reflected irradiance
+    are isotropic.
 
     Parameters
     ----------
@@ -524,6 +525,9 @@ def sapm(aoi, module, upper=None):
     r"""
     Determine the incidence angle modifier (IAM) using the SAPM model.
 
+    Procedures for determining the model coefficients are described in [2]_,
+    with angle of incidence measurement techniques discussed in [3]_.
+
     Parameters
     ----------
     aoi : numeric
@@ -1129,6 +1133,8 @@ def convert(source_name, source_params, target_name, weight=_sin_weight,
     """
     Convert a source IAM model to a target IAM model.
 
+    The conversion method is described in [1]_.
+
     Parameters
     ----------
     source_name : str
@@ -1248,6 +1254,8 @@ def fit(measured_aoi, measured_iam, model_name, weight=_sin_weight, xtol=None):
     """
     Find model parameters that best fit the data.
 
+    The fitting method is described in [1]_.
+
     Parameters
     ----------
     measured_aoi : array-like

pvlib/iotools/acis.py

@@ -427,6 +427,9 @@ def get_acis_available_stations(latitude_range, longitude_range,
     List weather stations in a given area available from the
     Applied Climate Information System (ACIS).
 
+    The service API is described in [1]_ and the station metadata fields
+    are described in [2]_.
+
     The ``sids`` returned by this function can be used with
     :py:func:`get_acis_station_data` to retrieve weather measurements
     from the station.

pvlib/iotools/pvgis.py

@@ -721,6 +721,8 @@ def read_pvgis_tmy(filename, pvgis_format=None, map_variables=True):
 def get_pvgis_horizon(latitude, longitude, url=URL, **kwargs):
     """Get horizon data from PVGIS.
 
+    The horizon profile tool is described in [1]_.
+
     Parameters
     ----------
     latitude : float