Merge branch 'main' into detect_clearsky_errors

Author: cwhanse

.github/workflows/publish.yml

@@ -33,9 +33,21 @@ jobs:
     - name: Build packages
       run: python -m build
 
+    - name: List distribution file sizes
+      run: du -h dist/*
+
     - name: Check metadata verification
       run: python -m twine check --strict dist/*
 
+    - name: Ensure that the wheel installs successfully
+      run: |
+        mkdir ./tmp
+        pip install $(find dist -type f -name "*.whl") --target=./tmp
+
+    - name: List installed file sizes
+      run: du -h pvlib
+      working-directory: ./tmp
+
     # only publish distribution to PyPI for tagged commits
     - name: Publish distribution to PyPI
       if: startsWith(github.ref, 'refs/tags/v')

docs/sphinx/source/_images/example_function_screenshot.png

@@ -13,7 +13,7 @@ pvlib python generally follows the `PEP 8 -- Style Guide for Python Code
 is 79 characters.
 
 pvlib python uses a mix of full and abbreviated variable names. See
-:ref:`variables_style_rules`. We could be better about consistency.
+:ref:`nomenclature`. 
 Prefer full names for new contributions. This is especially important
 for the API. Abbreviations can be used within a function to improve the
 readability of formulae.
@@ -163,7 +163,7 @@ An easy way to do this is with::
 
 Note: Anaconda users may have trouble using the above command to update an
 older version of docutils. If that happens, you can update it with ``conda``
-(e.g. ``conda install docutils=0.15.2``) and run the above command again.
+(e.g. ``conda install docutils=0.21``) and run the above command again.
 
 Once the ``doc`` dependencies are installed, navigate to ``/docs/sphinx`` and
 execute::
@@ -182,6 +182,116 @@ Note that Windows users need not have the ``make`` utility installed as pvlib
 includes a ``make.bat`` batch file that emulates its interface.
 
 
+.. _example-docstring:
+
+Example Docstring
+-----------------
+
+Here is a template for a function docstring that encapsulates the main
+features that may be used in any docstring. Note that not all sections are
+required for every function.
+
+.. code-block:: python
+
+    def example_function(poa_global, exponents, degree_symbol, time_ref='UT',
+                         optional_arg=None):
+        r"""
+        One-sentence summary of the function (no citations).
+
+        A longer description of the function. This can include citations
+        (references) to literature [1]_, websites [2]_, and other code elements
+        such as functions (:py:func:`pvlib.location.lookup_altitude`) and
+        classes (:py:class:`pvlib.location.Location`).
+
+        .. versionadded:: 0.0.1
+        There are many more purpose-specific directives, admonitions and such
+        available at `this link <admonitions>`_. E.g.: ``.. versionchanged::``,
+        ``.. deprecated::``,  ``.. note::`` and ``.. warning::``.
+
+        .. _admonitions: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#admonitions-messages-and-warnings
+
+        Parameters
+        ----------
+        poa_global : numeric
+            Plane-of-array global irradiance, see :term:`poa_global`. [Wm⁻²].
+        exponents : array-like
+            A list of exponents. [x⁰¹²³⁴⁵⁶⁷⁸⁹⁻].
+        degree_symbol : pandas.Series or pandas.DataFrame
+            It's different from superscript zero. [°].
+        time_ref : ``'UT'`` or ``'TST'``, default: ``'UT'``
+            ``'UT'`` (universal time) or ``'TST'`` (True Solar Time).
+        optional_arg : integer, optional
+            A description of ``optional_arg``. [Unitless].
+
+            Specify a suitable datatype for each parameter. Other common
+            data types include ``str``, ``bool``, ``float``, ``numeric``
+            and ``pandas.DatetimeIndex``.
+
+        Returns
+        -------
+        name : numeric
+            A description of the return value.
+
+        Raises
+        ------
+        ValueError
+            If ``poa_global`` is negative.
+        KeyError
+            If ``time_ref`` does not exist.
+
+        Notes
+        -----
+        This section can include additional information about the function.
+
+        For example, an equation using LaTeX markup:
+
+        .. math::
+
+            a = \left(\frac{b}{c}\right)^2
+
+        where :math:`a` is the result of the equation, and :math:`b` and :math:`c`
+        are inputs.
+
+        Or a figure with a caption:
+
+        .. figure:: ../../_images/pvlib_logo_horiz.png
+            :scale: 10%
+            :alt: alternate text
+            :align: center
+
+            Figure caption.
+
+        See Also
+        --------
+        pvlib.location.lookup_altitude, pvlib.location.Location
+
+        Examples
+        --------
+        >>> example_function(1, 1, pd.Series([1]), "TST", 2)
+        'Something'
+
+        References
+        ----------
+        A IEEE citation to a relevant reference. You may use an automatic
+        citation generator to format the citation correctly.
+
+        .. [1] Anderson, K., Hansen, C., Holmgren, W., Jensen, A., Mikofski, M.,
+           and Driesse, A. "pvlib python: 2023 project update." Journal of Open
+           Source Software, 8(92), 5994, (2023). :doi:`10.21105/joss.05994`.
+        .. [2] J. Smith and J. Doe. "Obama inaugurated as President." CNN.com.
+           Accessed: Feb. 1, 2009. [Online.]
+           Available: http://www.cnn.com/POLITICS/01/21/obama_inaugurated/index.html
+        """
+        a = "Some"
+        b = "thing"
+        return a + b
+
+A preview of how this docstring would render in the documentation can be seen in the
+following file: :download:`Example docstring<../_images/example_function_screenshot.png>`.
+
+Remember that to show the docstring in the documentation, you must list
+the function in the appropriate ``.rst`` file in the ``docs/sphinx/source/reference`` folder.
+
 .. _example-gallery:
 
 Example Gallery

docs/sphinx/source/contributing/style_guide.rst

@@ -26,7 +26,7 @@ pvlib python
 that-use-pvlib-python>`_ page for inspiration and listing of your
 application.
 
-There is a :ref:`variable naming convention <variables_style_rules>` to
+There is a :ref:`variable naming convention <nomenclature>` to
 ensure consistency throughout the library.
 
 

docs/sphinx/source/index.rst

@@ -15,6 +15,6 @@ User Guide
    clearsky
    bifacial
    weather_data
-   variables_style_rules
    singlediode
+   nomenclature
    faq

docs/sphinx/source/user_guide/index.rst

@@ -0,0 +1,192 @@
+.. _nomenclature:
+
+Nomenclature
+============
+
+There is a convention on consistent variable names throughout the library:
+
+.. glossary::
+
+    airmass
+        Airmass
+    
+    airmass_absolute
+        Absolute airmass
+    
+    airmass_relative
+        Relative airmass
+    
+    albedo
+        Ratio of reflected solar irradiance to global horizontal irradiance
+        [unitless]
+    
+    aoi
+        Angle of incidence. Angle between the surface normal vector and the
+        vector pointing towards the sun’s center
+    
+    aoi_projection
+        cos(aoi)
+
+    ape
+        Average photon energy
+
+    apparent_zenith
+        Refraction-corrected solar zenith angle in degrees
+
+    bhi
+        Beam/direct horizontal irradiance
+
+    dhi
+        Diffuse horizontal irradiance
+
+    dni
+        Direct normal irradiance [Wm⁻²]. Irradiance received per unit area by a
+        surface perpendicular (normal) to the sun's rays that propagate in a
+        straight line from the sun.
+
+    dni_clear
+        Clear sky direct normal irradiance
+
+    dni_extra
+        Direct normal irradiance at top of atmosphere (extraterrestrial)
+
+    effective_irradiance
+        Effective irradiance
+
+    eta_inv
+        Inverter efficiency
+
+    eta_inv_nom
+        Nominal inverter efficiency
+
+    eta_inv_ref
+        Reference inverter efficiency
+
+    g_poa_effective
+        Broadband plane of array effective irradiance
+
+    gamma_pdc
+        Module temperature coefficient. Typically in units of 1/C.
+
+    ghi
+        Global horizontal irradiance
+
+    ghi_extra
+        Horizontal irradiance at top of atmosphere (extraterrestrial)
+
+    gri
+        Ground-reflected irradiance
+
+    i_sc
+        Short circuit module current
+
+    i_x, i_xx
+        Sandia Array Performance Model IV curve parameters
+
+    latitude
+        Latitude
+
+    longitude
+        Longitude
+
+    pac, ac
+        AC power
+
+    pdc, dc
+        DC power
+
+    pdc0
+        Nameplate DC rating
+
+    photocurrent
+        Photocurrent
+
+    poa_diffuse
+        Total diffuse irradiation in plane. Sum of ground and sky diffuse.
+
+    poa_direct
+        Direct/beam irradiation in plane
+
+    poa_global
+        Global irradiation in plane. sum of diffuse and beam projection.
+
+    poa_ground_diffuse
+        In plane ground reflected irradiation
+
+    poa_sky_diffuse
+        Diffuse irradiation in plane from scattered light in the atmosphere
+        (without ground reflected irradiation)
+
+    precipitable_water
+        Total precipitable water contained in a column of unit cross section
+        from earth to top of atmosphere
+
+    pressure
+        Atmospheric pressure
+
+    relative_humidity
+        Relative humidity
+
+    resistance_series
+        Series resistance
+
+    resistance_shunt
+        Shunt resistance
+
+    saturation_current
+        Diode saturation current
+
+    solar_azimuth
+        Azimuth angle of the sun in degrees East of North
+
+    solar_zenith
+        Zenith angle of the sun in degrees
+
+    surface_azimuth
+        Azimuth angle of the surface
+
+    surface_tilt
+        Panel tilt from horizontal [°]. For example, a surface facing up = 0°,
+        surface facing horizon = 90°.
+
+    temp_air
+        Temperature of the air
+
+    temp_cell
+        Temperature of the cell
+
+    temp_dew
+        Dewpoint temperature
+
+    temp_module
+        Temperature of the module
+
+    transposition_factor
+        The gain ratio of the radiation on inclined plane to global horizontal
+        irradiation: :math:`\frac{poa\_global}{ghi}`
+
+    tz
+        Timezone
+
+    v_mp, i_mp, p_mp
+        Module voltage, current, power at the maximum power point
+
+    v_oc
+        Open circuit module voltage
+
+    wind_direction
+        Wind direction
+
+    wind_speed
+        Wind speed
+
+
+For further explanation of the variables, common symbols, and
+units, refer to the following sources from `SoDa Service <http://www.soda-pro.com/home>`_:
+
+   * `Acronyms, Terminology and Units <https://www.soda-pro.com/help/general/acronyms-terminology-and-units>`_
+   * `Plane orientations and radiation components <https://www.soda-pro.com/help/general/plane-orientations-and-radiation-components>`_
+   * `Time references <https://www.soda-pro.com/help/general/time-references>`_
+
+.. note:: These further references might not use the same terminology as
+          *pvlib*. But the physical process referred to is the same.