diff --git a/docs/sphinx/source/contributing/style_guide.rst b/docs/sphinx/source/contributing/style_guide.rst index 58faa59a9..cb1c180f6 100644 --- a/docs/sphinx/source/contributing/style_guide.rst +++ b/docs/sphinx/source/contributing/style_guide.rst @@ -70,6 +70,77 @@ the ``docs/readthedocs.org:pvlib-python`` link within the checks status box at the bottom of the pull request. +.. _references: + +References +---------- +pvlib-python is transitioning to the `IEEE reference style `_, +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]_ and technical reports [4]_. + + 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` + +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 `_, + followed by the DOI inside a set of backticks. + + .. _building-the-documentation: Building the documentation diff --git a/docs/sphinx/source/whatsnew/v0.11.2.rst b/docs/sphinx/source/whatsnew/v0.11.2.rst index 81d36fda6..ad49c39b4 100644 --- a/docs/sphinx/source/whatsnew/v0.11.2.rst +++ b/docs/sphinx/source/whatsnew/v0.11.2.rst @@ -15,6 +15,10 @@ Enhancements Documentation ~~~~~~~~~~~~~ * Edited docstrings for :py:func:`~pvlib.pvsystem.dc_ohms_from_percent` and + :py:func:`~pvlib.pvsystem.dc_ohmic_loss` for clarity. (:issue:`1601`, :pull:`2229`) +* Added a new reference style guide to the contributing page. + (:issue:`2202`, :pull:`2226`) + :py:func:`~pvlib.pvsystem.dc_ohmic_losses` for clarity. (:issue:`1601`, :pull:`2229`) * Updated :py:func:`~pvlib.irradiance.reindl` to include definitions of terms and a new "notes" section (:issue:`2183`, :pull:`2193`)