Update CAMS documentation (#2457)

* Update CAMS documentation

* Update v0.12.1.rst

* Move gridded dataset description to notes

* Fix whatsnew entry

* FIx previous whatsnew entry

* Add Marion to Whatsnew

* Update pvlib/iotools/sodapro.py

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

* Update pvlib/iotools/sodapro.py

* Update pvlib/iotools/sodapro.py

---------

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

Author: 3 people

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

@@ -42,8 +42,10 @@ Documentation
   (:issue:`2423`, :pull:`2426`)
 * Clarify which SAPM coefficients are required by the ``module`` parameter in
   :py:func:`~pvlib.pvsystem.sapm` (:issue:`2392`, :pull:`2435`)
-* Update references in :py:func`~pvlib.irradiance.get_extra_radiation`
-  (:issue:`2333`, :pull:`2347`)
+* Update references in :py:func:`~pvlib.irradiance.get_extra_radiation`
+  (:issue:`2333`, :pull:`2437`)
+* Update references in :py:func:`~pvlib.iotools.get_cams` and :py:func:`~pvlib.iotools.read_cams`
+  (:issue:`2427`, :pull:`2457`)
 
 Requirements
 ~~~~~~~~~~~~
@@ -68,3 +70,5 @@ Contributors
 * Will Holmgren (:ghuser:`wholmgren`)
 * Muhammad Rebaal (:ghuser:`Muhammad-Rebaal`)
 * omahs (:ghuser:`omahs`)
+* Adam R. Jensen (:ghuser:`AdamRJensen`)
+* Marion Schroedter-Homscheidt (:ghuser:`mschroedter`)

pvlib/iotools/sodapro.py

@@ -143,6 +143,12 @@ def get_cams(latitude, longitude, start, end, email, identifier='mcclear',
     e.g. `sza` becomes `solar_zenith`. See variable :const:`VARIABLE_MAP` for
     the complete mapping.
 
+    For large geospatial areas, CAMS offers a pre-calculated
+    gridded dataset [4]_ over land and coastal areas. This dataset
+    may not include the most recent data coverage and may not be
+    based on the most recent CAMS version. This dataset is not available
+    through pvlib.
+
     See Also
     --------
     pvlib.iotools.read_cams, pvlib.iotools.parse_cams
@@ -155,13 +161,15 @@ def get_cams(latitude, longitude, start, end, email, identifier='mcclear',
 
     References
     ----------
-    .. [1] `CAMS solar radiation documentation
-       <https://atmosphere.copernicus.eu/solar-radiation>`_
+    .. [1] `CAMS solar radiation time-series documentation. Climate Data Store.
+       <https://ads.atmosphere.copernicus.eu/datasets/cams-solar-radiation-timeseries>`_
     .. [2] `CAMS Radiation Automatic Access (SoDa)
        <https://www.soda-pro.com/help/cams-services/cams-radiation-service/automatic-access>`_
     .. [3] A. R. Jensen et al., pvlib iotools — Open-source Python functions
        for seamless access to solar irradiance data. Solar Energy. 2023. Vol
        266, pp. 112092. :doi:`10.1016/j.solener.2023.112092`
+    .. [4] `CAMS gridded solar radiation documentation.
+       <https://ads.atmosphere.copernicus.eu/datasets/cams-gridded-solar-radiation>`_
     """
     try:
         time_step_str = TIME_STEPS_MAP[time_step]
@@ -268,8 +276,8 @@ def parse_cams(fbuf, integrated=False, label=None, map_variables=True):
 
     References
     ----------
-    .. [1] `CAMS solar radiation documentation
-       <https://atmosphere.copernicus.eu/solar-radiation>`_
+    .. [1] `CAMS solar radiation time-series documentation. Climate Data Store.
+       <https://ads.atmosphere.copernicus.eu/datasets/cams-solar-radiation-timeseries>`_
     """
     metadata = {}
     # Initial lines starting with # contain metadata
@@ -370,8 +378,8 @@ def read_cams(filename, integrated=False, label=None, map_variables=True):
 
     References
     ----------
-    .. [1] `CAMS solar radiation documentation
-       <https://atmosphere.copernicus.eu/solar-radiation>`_
+    .. [1] `CAMS solar radiation time-series documentation. Climate Data Store.
+       <https://ads.atmosphere.copernicus.eu/datasets/cams-solar-radiation-timeseries>`_
     """
     with open(str(filename), 'r') as fbuf:
         content = parse_cams(fbuf, integrated, label, map_variables)