Merge branch 'main' into relative-humidity

Author: AdamRJensen

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,7 +1,7 @@
 <!-- Thank you for your contribution! The following items must be addressed before the code can be merged. Please don't hesitate to ask for help if you're unsure of how to accomplish any of the items. Feel free to remove checklist items that are not relevant to your change. -->
 
  - [ ] Closes #xxxx
- - [ ] I am familiar with the [contributing guidelines](https://pvlib-python.readthedocs.io/en/latest/contributing.html)
+ - [ ] I am familiar with the [contributing guidelines](https://pvlib-python.readthedocs.io/en/latest/contributing/index.html)
  - [ ] Tests added
  - [ ] Updates entries in [`docs/sphinx/source/reference`](https://github.com/pvlib/pvlib-python/blob/main/docs/sphinx/source/reference) for API changes.
  - [ ] Adds description and name entries in the appropriate "what's new" file in [`docs/sphinx/source/whatsnew`](https://github.com/pvlib/pvlib-python/tree/main/docs/sphinx/source/whatsnew) for all changes. Includes link to the GitHub Issue with `` :issue:`num` `` or this Pull Request with `` :pull:`num` ``. Includes contributor name and/or GitHub username (link with `` :ghuser:`user` ``).

.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

@@ -56,11 +56,28 @@
     'sphinx_gallery.gen_gallery',
     'sphinx_toggleprompt',
     'sphinx_favicon',
+    'hoverxref.extension',
 ]
 
 mathjax3_config = {'chtml': {'displayAlign': 'left',
                              'displayIndent': '2em'}}
 
+# Example configuration for intersphinx: refer to the Python standard library.
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3/', None),
+    'numpy': ('https://numpy.org/doc/stable/', None),
+    'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None),
+    'pandas': ('https://pandas.pydata.org/pandas-docs/stable', None),
+    'matplotlib': ('https://matplotlib.org/stable', None),
+}
+
+# Enable hover tooltips
+hoverxref_auto_ref = True
+hoverxref_roles = ["class", "meth", "func", "ref", "term"]
+hoverxref_role_types = dict.fromkeys(hoverxref_roles, "tooltip")
+hoverxref_domains = ["py"]
+hoverxref_intersphinx = list(intersphinx_mapping.keys())
+
 napoleon_use_rtype = False  # group rtype on same line together with return
 
 # Add any paths that contain templates here, relative to this directory.
@@ -357,15 +374,6 @@ def setup(app):
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 # texinfo_no_detailmenu = False
 
-# Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {
-    'python': ('https://docs.python.org/3/', None),
-    'numpy': ('https://numpy.org/doc/stable/', None),
-    'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None),
-    'pandas': ('https://pandas.pydata.org/pandas-docs/stable', None),
-    'matplotlib': ('https://matplotlib.org/stable', None),
-}
-
 ipython_warning_is_error = False
 
 # suppress "WARNING: Footnote [1] is not referenced." messages

docs/sphinx/source/conf.py

@@ -1,3 +1,5 @@
+.. _contributing:
+
 ============
 Contributing
 ============

docs/sphinx/source/contributing/index.rst

@@ -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.
@@ -70,7 +70,7 @@ the ``docs/readthedocs.org:pvlib-python`` link within the checks
 status box at the bottom of the pull request.
 
 
-.. _references:
+.. _reference_style:
 
 References
 ----------
@@ -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