Docstring cleanup: "default None", doi (#1828)

* Align reference

* Update irradiance.py

Exclude .*=| from negative lookahead

^(\s{8}|\s{4})(?!try|else|doi|DOI|Warning|Access|Requests|Note)(\w*): (?!.*:)(.+)$

Reason: just this line 🌝
Remaining matches are type annotations in modelchain.py and pvsystem.py

* Remove parenthesis in types

F: (?<spaces>\s{8}|\s{4})(?<name>\w*)\s?: (?<type>.*) \(optional, default=(?<default>.*)\)$
R:

* Remove none in type definition #1574

1st-F: (?<spaces> {8}| {4})(?<name>\w*) : (?<types>.*), default None$
2nd-F: (?<spaces> {8}| {4})(?<name>\w*) : [Nn}one or (?<type>.*), optional$
3rd-F: (?<spaces> {8}| {4})(?<name>\w*) : (?<type>.*) or [nN]one, optional$

R: $1$2 : $3, optional

* Change if none ocurrences (I)

F: If None,
R: If not specified,

* Change if none ocurrences (II)

F: If None
R: If not specified,

* Too long line

* Too long line

* fix doi external links

Regex find: (?:doi|DOI):(?!`)\s?(.*?)(\.\n|\n)
Replace: :doi:`$1`$2

* Apply cwhanse suggestion

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

* Apply cwhanse suggestion

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

* Apply cwhanse suggestion

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

* Apply cwhanse suggestion

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

* Modified cwhanse suggestion

Co-Authored-By: Cliff Hansen <[email protected]>

* Update modelchain.py

Co-Authored-By: Cliff Hansen <[email protected]>

* Some None's missed

F: (?<spaces> {8}| {4})(?<name>\w*) : [Nn]one[ ,]*(?<type>.*), optional$
R: $1$2 : $3, optional
Co-Authored-By: Cliff Hansen <[email protected]>

* ``none``'s, some more ``'s to variables and some other nones

Co-Authored-By: Cliff Hansen <[email protected]>

* Special ``none`` cases (please review)

Co-Authored-By: Cliff Hansen <[email protected]>

* Linter

Co-Authored-By: Cliff Hansen <[email protected]>

* Run more regexes

F1: (?<spaces> {8}| {4})(?<name>\w*) ?: (?<type>.*), default: None
F2: (?<spaces> {8}| {4})(?<name>\w*) ?: (?<types>.*), default None$
F3: (?<spaces> {8}| {4})(?<name>\w*) ?: [Nn]one or (?<type>.*), optional$     zero results
F4: (?<spaces> {8}| {4})(?<name>\w*) ?: (?<type>.*) or [nN]one, optional$     zero results

R: $1$2 : $3, optional

* More Nones

F: (?<spaces> {8}| {4})(?<name>\w*) ?: (?<type>.*), default:? None\.?
R: $1$2 : $3, optional

F: (?<spaces> {8}| {4})(?<name>\w*) ?: [Nn]one, (?<type>.*), default:? (?<def>.*)\.?
R: $1$2 : $3, default $4

F: (?<spaces> {8}| {4})(?<name>\w*) ?: [Nn]one or (?<types>.*)
R: $1$2 : $3

F: (?<spaces> {8}| {4})(?<name>\w*) ?: (?<types>.*) or [Nn]one(?<trailing>.*)
R: $1$2 : $3$4

F: (?<spaces> {8}| {4})(?<name>\w*) ?: [Nn]one(?:,|or) (?<types>.*)
R: $1$2 : $3

* Update irradiance.py

* Revert "Special ``none`` cases (please review)"

This reverts commit b8f942b.

* Apply suggestions from code review

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

* Update irradiance.py

* Update pvlib/irradiance.py

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

* Update irradiance.py

---------

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

Author: echedey-ls

pvlib/bifacial/utils.py

@@ -80,7 +80,7 @@ def _unshaded_ground_fraction(surface_tilt, surface_azimuth, solar_zenith,
     .. [1] Mikofski, M., Darawali, R., Hamer, M., Neubert, A., and Newmiller,
        J. "Bifacial Performance Modeling in Large Arrays". 2019 IEEE 46th
        Photovoltaic Specialists Conference (PVSC), 2019, pp. 1282-1287.
-       doi: 10.1109/PVSC40753.2019.8980572.
+       :doi:`10.1109/PVSC40753.2019.8980572`.
     """
     tan_phi = _solar_projection_tangent(solar_zenith, solar_azimuth,
                                         surface_azimuth)

pvlib/clearsky.py

@@ -159,7 +159,7 @@ def lookup_linke_turbidity(time, latitude, longitude, filepath=None,
 
     longitude : float or int
 
-    filepath : None or string, default None
+    filepath : string, optional
         The path to the ``.h5`` file.
 
     interp_turbidity : bool, default True
@@ -703,9 +703,9 @@ def detect_clearsky(measured, clearsky, times=None, infer_limits=False,
         Time series of measured GHI. [W/m2]
     clearsky : array or Series
         Time series of the expected clearsky GHI. [W/m2]
-    times : DatetimeIndex or None, default None.
-        Times of measured and clearsky values. If None the index of measured
-        will be used.
+    times : DatetimeIndex, optional
+        Times of measured and clearsky values. If not specified, the index of
+        ``measured`` will be used.
     infer_limits : bool, default False
         If True, does not use passed in kwargs (or defaults), but instead
         interpolates these values from Table 1 in [2]_.

pvlib/iam.py

@@ -124,7 +124,7 @@ def physical(aoi, n=1.526, K=4.0, L=0.002, *, n_ar=None):
 
     n_ar : numeric, optional
         The effective index of refraction of the anti-reflective (AR) coating
-        (unitless). If n_ar is None (default), no AR coating is applied.
+        (unitless). If ``n_ar`` is not supplied, no AR coating is applied.
         A typical value for the effective index of an AR coating is 1.29.
 
     Returns
@@ -338,7 +338,7 @@ def martin_ruiz_diffuse(surface_tilt, a_r=0.16, c1=0.4244, c2=None):
     c2 : float
         Second fitting parameter for the expressions that approximate the
         integral of diffuse irradiance coming from different directions.
-        If c2 is None, it will be calculated according to the linear
+        If c2 is not specified, it will be calculated according to the linear
         relationship given in [3]_.
 
     Returns
@@ -514,7 +514,7 @@ def sapm(aoi, module, upper=None):
         A dict or Series with the SAPM IAM model parameters.
         See the :py:func:`sapm` notes section for more details.
 
-    upper : None or float, default None
+    upper : float, optional
         Upper limit on the results.
 
     Returns
@@ -541,7 +541,7 @@ def sapm(aoi, module, upper=None):
 
     .. [3] B.H. King et al, "Recent Advancements in Outdoor Measurement
        Techniques for Angle of Incidence Effects," 42nd IEEE PVSC (2015).
-       DOI: 10.1109/PVSC.2015.7355849
+       :doi:`10.1109/PVSC.2015.7355849`
 
     See Also
     --------
@@ -607,7 +607,7 @@ def marion_diffuse(model, surface_tilt, **kwargs):
     .. [1] B. Marion "Numerical method for angle-of-incidence correction
        factors for diffuse radiation incident photovoltaic modules",
        Solar Energy, Volume 147, Pages 344-348. 2017.
-       DOI: 10.1016/j.solener.2017.03.027
+       :doi:`10.1016/j.solener.2017.03.027`
 
     Examples
     --------
@@ -694,7 +694,7 @@ def marion_integrate(function, surface_tilt, region, num=None):
     .. [1] B. Marion "Numerical method for angle-of-incidence correction
        factors for diffuse radiation incident photovoltaic modules",
        Solar Energy, Volume 147, Pages 344-348. 2017.
-       DOI: 10.1016/j.solener.2017.03.027
+       :doi:`10.1016/j.solener.2017.03.027`
 
     Examples
     --------

pvlib/iotools/epw.py

@@ -25,7 +25,7 @@ def read_epw(filename, coerce_year=None):
     filename : String
         Can be a relative file path, absolute file path, or url.
 
-    coerce_year : None or int, default None
+    coerce_year : int, optional
         If supplied, the year of the data will be set to this value. This can
         be a useful feature because EPW data is composed of data from
         different years.
@@ -247,7 +247,7 @@ def parse_epw(csvdata, coerce_year=None):
     csvdata : file-like buffer
         a file-like buffer containing data in the EPW format
 
-    coerce_year : None or int, default None
+    coerce_year : int, optional
         If supplied, the year of the data will be set to this value. This can
         be a useful feature because EPW data is composed of data from
         different years.

pvlib/iotools/pvgis.py

@@ -63,13 +63,13 @@ def get_pvgis_hourly(latitude, longitude, start=None, end=None,
         In decimal degrees, between -90 and 90, north is positive (ISO 19115)
     longitude: float
         In decimal degrees, between -180 and 180, east is positive (ISO 19115)
-    start: int or datetime like, default: None
+    start : int or datetime like, optional
         First year of the radiation time series. Defaults to first year
         available.
-    end: int or datetime like, default: None
+    end : int or datetime like, optional
         Last year of the radiation time series. Defaults to last year
         available.
-    raddatabase: str, default: None
+    raddatabase : str, optional
         Name of radiation database. Options depend on location, see [3]_.
     components: bool, default: True
         Output solar radiation components (beam, diffuse, and reflected).
@@ -87,14 +87,14 @@ def get_pvgis_hourly(latitude, longitude, start=None, end=None,
            and pvlib<=0.9.5 is offset by 180 degrees.
     usehorizon: bool, default: True
         Include effects of horizon
-    userhorizon: list of float, default: None
+    userhorizon : list of float, optional
         Optional user specified elevation of horizon in degrees, at equally
         spaced azimuth clockwise from north, only valid if ``usehorizon`` is
-        true, if ``usehorizon`` is true but ``userhorizon`` is ``None`` then
+        true, if ``usehorizon`` is true but ``userhorizon`` is not specified then
         PVGIS will calculate the horizon [4]_
     pvcalculation: bool, default: False
         Return estimate of hourly PV production.
-    peakpower: float, default: None
+    peakpower : float, optional
         Nominal power of PV system in kW. Required if pvcalculation=True.
     pvtechchoice: {'crystSi', 'CIS', 'CdTe', 'Unknown'}, default: 'crystSi'
         PV technology.
@@ -309,12 +309,12 @@ def read_pvgis_hourly(filename, pvgis_format=None, map_variables=True):
     ----------
     filename : str, pathlib.Path, or file-like buffer
         Name, path, or buffer of hourly data file downloaded from PVGIS.
-    pvgis_format : str, default None
+    pvgis_format : str, optional
         Format of PVGIS file or buffer. Equivalent to the ``outputformat``
         parameter in the PVGIS API. If ``filename`` is a file and
-        ``pvgis_format`` is ``None`` then the file extension will be used to
-        determine the PVGIS format to parse. If ``filename`` is a buffer, then
-        ``pvgis_format`` is required and must be in ``['csv', 'json']``.
+        ``pvgis_format`` is not specified then the file extension will be used
+        to determine the PVGIS format to parse. If ``filename`` is a buffer,
+        then ``pvgis_format`` is required and must be in ``['csv', 'json']``.
     map_variables: bool, default True
         When true, renames columns of the DataFrame to pvlib variable names
         where applicable. See variable :const:`VARIABLE_MAP`.
@@ -336,11 +336,11 @@ def read_pvgis_hourly(filename, pvgis_format=None, map_variables=True):
     Raises
     ------
     ValueError
-        if ``pvgis_format`` is ``None`` and the file extension is neither
+        if ``pvgis_format`` is not specified and the file extension is neither
         ``.csv`` nor ``.json`` or if ``pvgis_format`` is provided as
         input but isn't in ``['csv', 'json']``
     TypeError
-        if ``pvgis_format`` is ``None`` and ``filename`` is a buffer
+        if ``pvgis_format`` is not specified and ``filename`` is a buffer
 
     See Also
     --------
@@ -409,14 +409,13 @@ def get_pvgis_tmy(latitude, longitude, outputformat='json', usehorizon=True,
         documentation [2]_ for more info.
     usehorizon : bool, default True
         include effects of horizon
-    userhorizon : list of float, default None
-        optional user specified elevation of horizon in degrees, at equally
-        spaced azimuth clockwise from north, only valid if ``usehorizon`` is
-        true, if ``usehorizon`` is true but ``userhorizon`` is ``None`` then
-        PVGIS will calculate the horizon [3]_
-    startyear : int, default None
+    userhorizon : list of float, optional
+        Optional user-specified elevation of horizon in degrees, at equally
+        spaced azimuth clockwise from north. If not specified, PVGIS will
+        calculate the horizon [3]_. If specified, requires ``usehorizon=True``.
+    startyear : int, optional
         first year to calculate TMY
-    endyear : int, default None
+    endyear : int, optional
         last year to calculate TMY, must be at least 10 years from first year
     map_variables: bool, default True
         When true, renames columns of the Dataframe to pvlib variable names
@@ -573,12 +572,13 @@ def read_pvgis_tmy(filename, pvgis_format=None, map_variables=True):
     ----------
     filename : str, pathlib.Path, or file-like buffer
         Name, path, or buffer of file downloaded from PVGIS.
-    pvgis_format : str, default None
+    pvgis_format : str, optional
         Format of PVGIS file or buffer. Equivalent to the ``outputformat``
         parameter in the PVGIS TMY API. If ``filename`` is a file and
-        ``pvgis_format`` is ``None`` then the file extension will be used to
-        determine the PVGIS format to parse. For PVGIS files from the API with
-        ``outputformat='basic'``, please set ``pvgis_format`` to ``'basic'``.
+        ``pvgis_format`` is not specified then the file extension will be used
+        to determine the PVGIS format to parse. For PVGIS files from the API
+        with ``outputformat='basic'``, please set ``pvgis_format`` to
+        ``'basic'``.
         If ``filename`` is a buffer, then ``pvgis_format`` is required and must
         be in ``['csv', 'epw', 'json', 'basic']``.
     map_variables: bool, default True
@@ -600,11 +600,11 @@ def read_pvgis_tmy(filename, pvgis_format=None, map_variables=True):
     Raises
     ------
     ValueError
-        if ``pvgis_format`` is ``None`` and the file extension is neither
+        if ``pvgis_format`` is not specified and the file extension is neither
         ``.csv``, ``.json``, nor ``.epw``, or if ``pvgis_format`` is provided
         as input but isn't in ``['csv', 'epw', 'json', 'basic']``
     TypeError
-        if ``pvgis_format`` is ``None`` and ``filename`` is a buffer
+        if ``pvgis_format`` is not specified and ``filename`` is a buffer
 
     See Also
     --------

pvlib/iotools/sodapro.py

@@ -75,8 +75,8 @@ def get_cams(latitude, longitude, start, end, email, identifier='mcclear',
     identifier: {'mcclear', 'cams_radiation'}
         Specify whether to retrieve CAMS Radiation or McClear parameters
     altitude: float, optional
-        Altitude in meters. If None, then the altitude is determined from the
-        NASA SRTM database
+        Altitude in meters. If not specified, then the altitude is determined
+        from the NASA SRTM database
     time_step: str, {'1min', '15min', '1h', '1d', '1M'}, default: '1h'
         Time step of the time series, either 1 minute, 15 minute, hourly,
         daily, or monthly.
@@ -88,7 +88,7 @@ def get_cams(latitude, longitude, start, end, email, identifier='mcclear',
     integrated: boolean, default False
         Whether to return radiation parameters as integrated values (Wh/m^2)
         or as average irradiance values (W/m^2) (pvlib preferred units)
-    label: {'right', 'left'}, default: None
+    label : {'right', 'left'}, optional
         Which bin edge label to label time-step with. The default is 'left' for
         all time steps except for '1M' which has a default of 'right'.
     map_variables: bool, default: True
@@ -241,7 +241,7 @@ def parse_cams(fbuf, integrated=False, label=None, map_variables=True):
     integrated: boolean, default False
         Whether to return radiation parameters as integrated values (Wh/m^2)
         or as average irradiance values (W/m^2) (pvlib preferred units)
-    label: {'right', 'left'}, default: None
+    label : {'right', 'left'}, optional
         Which bin edge label to label time-step with. The default is 'left' for
         all time steps except for '1M' which has a default of 'right'.
     map_variables: bool, default: True
@@ -342,7 +342,7 @@ def read_cams(filename, integrated=False, label=None, map_variables=True):
     integrated: boolean, default False
         Whether to return radiation parameters as integrated values (Wh/m^2)
         or as average irradiance values (W/m^2) (pvlib preferred units)
-    label: {'right', 'left}, default: None
+    label : {'right', 'left}, optional
         Which bin edge label to label time-step with. The default is 'left' for
         all time steps except for '1M' which has a default of 'right'.
     map_variables: bool, default: True

pvlib/iotools/tmy.py

@@ -40,11 +40,11 @@ def read_tmy3(filename, coerce_year=None, map_variables=None, recolumn=None,
     ----------
     filename : str
         A relative file path or absolute file path.
-    coerce_year : None or int, default None
-        If supplied, the year of the index will be set to `coerce_year`, except
+    coerce_year : int, optional
+        If supplied, the year of the index will be set to ``coerce_year``, except
         for the last index value which will be set to the *next* year so that
         the index increases monotonically.
-    map_variables : bool, default None
+    map_variables : bool, optional
         When True, renames columns of the DataFrame to pvlib variable names
         where applicable. See variable :const:`VARIABLE_MAP`.
     recolumn : bool (deprecated, use map_variables instead)