Merge branch 'main' into docstring-guidelines-units-etc

Author: echedey-ls

.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')

.github/workflows/top-ranked-issues.yml

@@ -0,0 +1,34 @@
+name: Update Top Ranked Issues
+
+on:
+  schedule:
+    # Runs every day at 00:00 AM UTC
+    - cron: '0 0 * * *'
+
+jobs:
+  run-script:
+    runs-on: ubuntu-latest
+
+    # Run only if the repository is pvlib/pvlib-python
+    if: ${{ github.repository == 'pvlib/pvlib-python' }}
+
+    env:
+      GITHUB_ACCESS_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+    steps:
+      - name: Check out the repository
+        uses: actions/checkout@v4  # This ensures the repository code is available
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install PyGithub
+
+      - name: Run update_top_ranking_issues.py
+        run: |
+          python ./scripts/update_top_ranking_issues.py

README.md

@@ -81,7 +81,7 @@ Contributing
 ============
 
 We need your help to make pvlib-python a great tool!
-Please see the [Contributing page](http://pvlib-python.readthedocs.io/en/stable/contributing.html) for more on how you can contribute.
+Please see the [Contributing page](https://pvlib-python.readthedocs.io/en/stable/contributing/index.html) for more on how you can contribute.
 The long-term success of pvlib-python requires substantial community support.
 
 

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.
@@ -90,6 +90,82 @@ When specifying parameters and their units, please follow these guidelines:
       dni : numeric
           Direct normal irradiance, see :term:`dni`. [Wm⁻²]
 
+
+.. _reference_style:
+
+References
+----------
+pvlib-python is transitioning to the `IEEE reference style <https://journals.ieeeauthorcenter.ieee.org/wp-content/uploads/sites/7/IEEE_Reference_Guide.pdf>`_,
+which should be used in all new contributions. At minimum, a reference should
+include:
+
+* Author list (for more than six authors, list only the first with et al.)
+* Publication title
+* Publisher (journal title, laboratory name, etc.)
+* Year of publication
+* DOI (if available)
+
+The recommended citation style for several media types is as follows:
+
+**Journal article**:
+
+    Author initials and surname, "Title of article," abbreviated journal
+    title, vol. number, issue number, page numbers, Abbreviated Month Year.
+
+**Book**:
+
+    Author initials. Author Surname, "Chapter title" in Book Title, xth ed.
+    City of Publisher, (only U.S. State), Country: Abbrev. of Publisher, year,
+    ch. x, sec. x, pp. xxx–xxx.
+
+**Technical report**:
+
+    Author initials. Author Surname, "Report title" Abbrev. publisher name,
+    City of publisher, Abbrev. State, Country, Rep. xxx, year
+
+The example below shows how to cite material and generate a reference list
+using the IEEE style in a docstring::
+
+    This is the recommended citation for the pvlib-python project [1]_. There
+    are also some conference papers linked to pvlib, for example [2]_.
+    
+    Other types of reference you may find in the pvlib-python documentation
+    include books [3]_, technical reports [4]_, and websites [5]_.
+
+    References
+    ----------
+    .. [1] K. Anderson, C. Hansen, W. Holmgren, A. Jensen, M. Mikofski,
+           and A Driesse. "pvlib python: 2023 project update." J. Open Source
+           Softw. vol. 8, no. 92, pp. 5994, Dec 2023,
+           :doi:`10.21105/joss.05994`.
+
+    .. [2] J. S. Stein, "The Photovoltaic Performance Modeling Collaborative
+           (PVPMC)," In Proc. 38th IEEE Photovoltaic Specialists Conference
+           (PVSC), Austin, TX, USA, 2012, pp. 3048-3052,
+           :doi:`10.1109/PVSC.2012.6318225`.
+
+    .. [3] J. A. Duffie and W. A. Beckman, "Solar Radiation" in Solar
+           Engineering of Thermal Processes, 3rd ed, New York, USA, J. Wiley
+           and Sons, 2006, ch. 1, sec. 1.5, pp.9-11.
+
+    .. [4] R. Bird and C. Riordan, "Simple solar spectral model for direct and
+           diffuse irradiance on horizontal and tilted planes at the earth’s
+           surface for cloudless atmospheres", NREL, Golden, CO, USA, Technical
+           Report TR-215-2436, 1984, :doi:`10.2172/5986936`.
+
+    .. [5] "PVPMC Home." Sandia National Laboratories PV Performance Modeling
+           Collaborative. Accessed: Oct. 17, 2024. [Online.] Available:
+           <https://pvpmc.sandia.gov/>_
+
+Things to note:
+
+* In-text numeric citations are a number inside square brackets, followed
+  by an underscore, e.g. ``[1]_``.
+* To include a DOI, you can use pvlib's custom ``:doi:``
+  `Sphinx role <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html>`_,
+  followed by the DOI inside a set of backticks.
+
+
 .. _building-the-documentation:
 
 Building the documentation
@@ -108,7 +184,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::
@@ -127,6 +203,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

@@ -1,7 +1,7 @@
 .. _testing:
 
-Testing
-=======
+Testing and benchmarking
+========================
 
 .. _overview:
 

docs/sphinx/source/contributing/testing.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.