From f75cfd86ea0d6230268420364907d0bef3677189 Mon Sep 17 00:00:00 2001 From: echedey-ls <80125792+echedey-ls@users.noreply.github.com> Date: Mon, 30 Sep 2024 22:53:47 +0100 Subject: [PATCH 01/13] Fix external link that can be an internal cross reference --- .../source/contributing/how_to_contribute_new_code.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/sphinx/source/contributing/how_to_contribute_new_code.rst b/docs/sphinx/source/contributing/how_to_contribute_new_code.rst index 19ac19dc41..ca08436ab1 100644 --- a/docs/sphinx/source/contributing/how_to_contribute_new_code.rst +++ b/docs/sphinx/source/contributing/how_to_contribute_new_code.rst @@ -153,8 +153,7 @@ We strongly recommend using virtual environments for development. Virtual environments make it easier to switch between different versions of software. This `scientific-python.org guide `_ -is a good reference for virtual environments. The pvlib-python `installation -user guide `_ also provides instructions on +is a good reference for virtual environments. The pvlib-python +:ref:`installation guide ` also provides instructions on setting up a virtual environment. If this is your first pull request, don't worry about using a virtual environment. From d5af4a0712eab7a7a2d7eaf641565dad0848fa3e Mon Sep 17 00:00:00 2001 From: echedey-ls <80125792+echedey-ls@users.noreply.github.com> Date: Wed, 9 Oct 2024 17:34:39 +0200 Subject: [PATCH 02/13] Update style_guide.rst --- .../source/contributing/style_guide.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/sphinx/source/contributing/style_guide.rst b/docs/sphinx/source/contributing/style_guide.rst index 58faa59a98..19fb7cf8b8 100644 --- a/docs/sphinx/source/contributing/style_guide.rst +++ b/docs/sphinx/source/contributing/style_guide.rst @@ -70,6 +70,25 @@ the ``docs/readthedocs.org:pvlib-python`` link within the checks status box at the bottom of the pull request. +.. _documentation-units: + +Parameter names and units +------------------------- + +When specifying parameters and their units, please follow these guidelines: +- Use the recommended parameter name and units by :ref:`variables_style_rules` where possible. +- Enclose units in square brackets, e.g. ``[W]``. +- Use unicode superscripts symbols for exponents, e.g. ``m²``. + + These superscripts characters are ``⁰``, ``¹``, ``²``, ``³``, ``⁴``, ``⁵``, ``⁶``, ``⁷``, ``⁸``, ``⁹``, ``⁺``, ``⁻``. Degree symbol is ``°``. + +- Link to a brief description of the magnitude in the :ref:`variables_style_rules` section if it exists, via the sphinx role |:term:`glossary_term`|. For example, to document ``dni`` use: + + .. code-block:: rst + + dni : numeric + Direct normal irradiance, see :term:`dni`. [Wm⁻²] + .. _building-the-documentation: Building the documentation From 842c9334f23fe4c090d20710994c723f67b56785 Mon Sep 17 00:00:00 2001 From: echedey-ls <80125792+echedey-ls@users.noreply.github.com> Date: Wed, 9 Oct 2024 17:38:41 +0200 Subject: [PATCH 03/13] Minor improvements to docs --- docs/sphinx/source/reference/tracking.rst | 3 --- docs/sphinx/source/reference/transformer.rst | 2 +- 2 files changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/sphinx/source/reference/tracking.rst b/docs/sphinx/source/reference/tracking.rst index 6d3f7fc4eb..4e85ffa3de 100644 --- a/docs/sphinx/source/reference/tracking.rst +++ b/docs/sphinx/source/reference/tracking.rst @@ -3,9 +3,6 @@ Tracking ======== -Functions ---------- - .. autosummary:: :toctree: generated/ diff --git a/docs/sphinx/source/reference/transformer.rst b/docs/sphinx/source/reference/transformer.rst index 293f301296..da2c6828ac 100644 --- a/docs/sphinx/source/reference/transformer.rst +++ b/docs/sphinx/source/reference/transformer.rst @@ -3,7 +3,7 @@ Transformer losses ================== -Methods to account for losses in transformers +Functions to account for losses in transformers .. autosummary:: :toctree: generated/ From e4629dee7a79bb34d1a533cad0dbcea3181dde1b Mon Sep 17 00:00:00 2001 From: echedey-ls <80125792+echedey-ls@users.noreply.github.com> Date: Wed, 9 Oct 2024 17:59:20 +0200 Subject: [PATCH 04/13] Update style_guide.rst --- docs/sphinx/source/contributing/style_guide.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/sphinx/source/contributing/style_guide.rst b/docs/sphinx/source/contributing/style_guide.rst index 19fb7cf8b8..f20e420830 100644 --- a/docs/sphinx/source/contributing/style_guide.rst +++ b/docs/sphinx/source/contributing/style_guide.rst @@ -79,7 +79,6 @@ When specifying parameters and their units, please follow these guidelines: - Use the recommended parameter name and units by :ref:`variables_style_rules` where possible. - Enclose units in square brackets, e.g. ``[W]``. - Use unicode superscripts symbols for exponents, e.g. ``m²``. - These superscripts characters are ``⁰``, ``¹``, ``²``, ``³``, ``⁴``, ``⁵``, ``⁶``, ``⁷``, ``⁸``, ``⁹``, ``⁺``, ``⁻``. Degree symbol is ``°``. - Link to a brief description of the magnitude in the :ref:`variables_style_rules` section if it exists, via the sphinx role |:term:`glossary_term`|. For example, to document ``dni`` use: From 12d8875550d4bc73a52a524a32fa87377cbc280d Mon Sep 17 00:00:00 2001 From: echedey-ls <80125792+echedey-ls@users.noreply.github.com> Date: Wed, 9 Oct 2024 18:08:53 +0200 Subject: [PATCH 05/13] Update style_guide.rst --- docs/sphinx/source/contributing/style_guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sphinx/source/contributing/style_guide.rst b/docs/sphinx/source/contributing/style_guide.rst index f20e420830..4866b62090 100644 --- a/docs/sphinx/source/contributing/style_guide.rst +++ b/docs/sphinx/source/contributing/style_guide.rst @@ -81,7 +81,7 @@ When specifying parameters and their units, please follow these guidelines: - Use unicode superscripts symbols for exponents, e.g. ``m²``. These superscripts characters are ``⁰``, ``¹``, ``²``, ``³``, ``⁴``, ``⁵``, ``⁶``, ``⁷``, ``⁸``, ``⁹``, ``⁺``, ``⁻``. Degree symbol is ``°``. -- Link to a brief description of the magnitude in the :ref:`variables_style_rules` section if it exists, via the sphinx role |:term:`glossary_term`|. For example, to document ``dni`` use: +- Link to a brief description of the magnitude in the :ref:`variables_style_rules` section if it exists, via the sphinx role ``:term:`glossary_term```. For example, to document ``dni`` use: .. code-block:: rst From d1737e98a2b3187a9f9e5bd4b4d8bc5a980e2521 Mon Sep 17 00:00:00 2001 From: echedey-ls <80125792+echedey-ls@users.noreply.github.com> Date: Wed, 9 Oct 2024 18:13:47 +0200 Subject: [PATCH 06/13] Update style_guide.rst --- docs/sphinx/source/contributing/style_guide.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/sphinx/source/contributing/style_guide.rst b/docs/sphinx/source/contributing/style_guide.rst index 4866b62090..02c80d02ca 100644 --- a/docs/sphinx/source/contributing/style_guide.rst +++ b/docs/sphinx/source/contributing/style_guide.rst @@ -76,9 +76,11 @@ Parameter names and units ------------------------- When specifying parameters and their units, please follow these guidelines: + - Use the recommended parameter name and units by :ref:`variables_style_rules` where possible. - Enclose units in square brackets, e.g. ``[W]``. - Use unicode superscripts symbols for exponents, e.g. ``m²``. + These superscripts characters are ``⁰``, ``¹``, ``²``, ``³``, ``⁴``, ``⁵``, ``⁶``, ``⁷``, ``⁸``, ``⁹``, ``⁺``, ``⁻``. Degree symbol is ``°``. - Link to a brief description of the magnitude in the :ref:`variables_style_rules` section if it exists, via the sphinx role ``:term:`glossary_term```. For example, to document ``dni`` use: From f2aa750768f33697150b2ce42d56c604df39c812 Mon Sep 17 00:00:00 2001 From: echedey-ls <80125792+echedey-ls@users.noreply.github.com> Date: Wed, 9 Oct 2024 21:20:05 +0200 Subject: [PATCH 07/13] Update style_guide.rst Co-Authored-By: RDaxini <143435106+RDaxini@users.noreply.github.com> --- docs/sphinx/source/contributing/style_guide.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sphinx/source/contributing/style_guide.rst b/docs/sphinx/source/contributing/style_guide.rst index 02c80d02ca..4d42668434 100644 --- a/docs/sphinx/source/contributing/style_guide.rst +++ b/docs/sphinx/source/contributing/style_guide.rst @@ -81,9 +81,9 @@ When specifying parameters and their units, please follow these guidelines: - Enclose units in square brackets, e.g. ``[W]``. - Use unicode superscripts symbols for exponents, e.g. ``m²``. - These superscripts characters are ``⁰``, ``¹``, ``²``, ``³``, ``⁴``, ``⁵``, ``⁶``, ``⁷``, ``⁸``, ``⁹``, ``⁺``, ``⁻``. Degree symbol is ``°``. + These superscripts characters are ``⁰``, ``¹``, ``²``, ``³``, ``⁴``, ``⁵``, ``⁶``, ``⁷``, ``⁸``, ``⁹``, ``⁻``. Degree symbol is ``°``. -- Link to a brief description of the magnitude in the :ref:`variables_style_rules` section if it exists, via the sphinx role ``:term:`glossary_term```. For example, to document ``dni`` use: +- Link to a brief description in the :ref:`variables_style_rules` section if it exists, via the sphinx role ``:term:`glossary_term```. For example, to document ``dni`` use: .. code-block:: rst From 52596a96dca2f1675437934a74d82c3ec4acd501 Mon Sep 17 00:00:00 2001 From: Echedey Luis <80125792+echedey-ls@users.noreply.github.com> Date: Wed, 27 Nov 2024 20:50:21 +0000 Subject: [PATCH 08/13] Update docs/sphinx/source/contributing/style_guide.rst Co-authored-by: RDaxini <143435106+RDaxini@users.noreply.github.com> --- docs/sphinx/source/contributing/style_guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sphinx/source/contributing/style_guide.rst b/docs/sphinx/source/contributing/style_guide.rst index 4d42668434..760a566106 100644 --- a/docs/sphinx/source/contributing/style_guide.rst +++ b/docs/sphinx/source/contributing/style_guide.rst @@ -77,7 +77,7 @@ Parameter names and units When specifying parameters and their units, please follow these guidelines: -- Use the recommended parameter name and units by :ref:`variables_style_rules` where possible. +- Use the recommended parameter name and units by :ref:`nomenclature` where possible. - Enclose units in square brackets, e.g. ``[W]``. - Use unicode superscripts symbols for exponents, e.g. ``m²``. From fa25f223acda1e102181c08f04af19564486e148 Mon Sep 17 00:00:00 2001 From: Echedey Luis <80125792+echedey-ls@users.noreply.github.com> Date: Thu, 28 Nov 2024 11:58:42 +0000 Subject: [PATCH 09/13] Update docs/sphinx/source/contributing/style_guide.rst Co-authored-by: Adam R. Jensen <39184289+AdamRJensen@users.noreply.github.com> --- docs/sphinx/source/contributing/style_guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sphinx/source/contributing/style_guide.rst b/docs/sphinx/source/contributing/style_guide.rst index d3043774c1..e8794496de 100644 --- a/docs/sphinx/source/contributing/style_guide.rst +++ b/docs/sphinx/source/contributing/style_guide.rst @@ -77,7 +77,7 @@ Parameter names and units When specifying parameters and their units, please follow these guidelines: -- Use the recommended parameter name and units by :ref:`nomenclature` where possible. +- Use the recommended parameter name and units listed in the :ref:`nomenclature` where applicable. - Enclose units in square brackets, e.g. ``[W]``. - Use unicode superscripts symbols for exponents, e.g. ``m²``. From 5f8261557273c2b6e66a3a508d85d0b5e3d5c7ba Mon Sep 17 00:00:00 2001 From: Echedey Luis <80125792+echedey-ls@users.noreply.github.com> Date: Thu, 28 Nov 2024 11:59:36 +0000 Subject: [PATCH 10/13] Apply suggestions from code review Co-authored-by: Adam R. Jensen <39184289+AdamRJensen@users.noreply.github.com> --- docs/sphinx/source/contributing/style_guide.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/sphinx/source/contributing/style_guide.rst b/docs/sphinx/source/contributing/style_guide.rst index e8794496de..9f5e4c0f81 100644 --- a/docs/sphinx/source/contributing/style_guide.rst +++ b/docs/sphinx/source/contributing/style_guide.rst @@ -78,11 +78,11 @@ Parameter names and units When specifying parameters and their units, please follow these guidelines: - Use the recommended parameter name and units listed in the :ref:`nomenclature` where applicable. -- Enclose units in square brackets, e.g. ``[W]``. -- Use unicode superscripts symbols for exponents, e.g. ``m²``. - - These superscripts characters are ``⁰``, ``¹``, ``²``, ``³``, ``⁴``, ``⁵``, ``⁶``, ``⁷``, ``⁸``, ``⁹``, ``⁻``. Degree symbol is ``°``. - +- Enclose units in square brackets after the parameter description, e.g., ``Air temperature. [°C]``. +- Use unicode superscripts symbols for exponents, e.g. ``m⁻²``. + - Numbers: ``⁰``, ``¹``, ``²``, ``³``, ``⁴``, ``⁵``, ``⁶``, ``⁷``, ``⁸``, ``⁹`` + - Negative exponent: ``⁻`` + - Degree symbol: ``°`` - Link to a brief description in the :ref:`variables_style_rules` section if it exists, via the sphinx role ``:term:`glossary_term```. For example, to document ``dni`` use: .. code-block:: rst From 6bd2b056e788165ef8704657ca4969e7756fc272 Mon Sep 17 00:00:00 2001 From: echedey-ls <80125792+echedey-ls@users.noreply.github.com> Date: Thu, 28 Nov 2024 12:01:52 +0000 Subject: [PATCH 11/13] Fix link variables_style_rules -> nomenclature Co-Authored-By: Adam R. Jensen <39184289+AdamRJensen@users.noreply.github.com> --- docs/sphinx/source/contributing/style_guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sphinx/source/contributing/style_guide.rst b/docs/sphinx/source/contributing/style_guide.rst index 9f5e4c0f81..6375ff7b9c 100644 --- a/docs/sphinx/source/contributing/style_guide.rst +++ b/docs/sphinx/source/contributing/style_guide.rst @@ -83,7 +83,7 @@ When specifying parameters and their units, please follow these guidelines: - Numbers: ``⁰``, ``¹``, ``²``, ``³``, ``⁴``, ``⁵``, ``⁶``, ``⁷``, ``⁸``, ``⁹`` - Negative exponent: ``⁻`` - Degree symbol: ``°`` -- Link to a brief description in the :ref:`variables_style_rules` section if it exists, via the sphinx role ``:term:`glossary_term```. For example, to document ``dni`` use: +- Link to a brief description in the :ref:`nomenclature` section if it exists, via the sphinx role ``:term:`glossary_term```. For example, to document ``dni`` use: .. code-block:: rst From 907ff359d60ba57188c23c7ac3043c716f14c1d8 Mon Sep 17 00:00:00 2001 From: echedey-ls <80125792+echedey-ls@users.noreply.github.com> Date: Thu, 28 Nov 2024 13:49:21 +0000 Subject: [PATCH 12/13] =?UTF-8?q?Fix=20bulleted=20list=20(hopefully=20?= =?UTF-8?q?=F0=9F=99=8F=20)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/sphinx/source/contributing/style_guide.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/sphinx/source/contributing/style_guide.rst b/docs/sphinx/source/contributing/style_guide.rst index 6375ff7b9c..4eea571eda 100644 --- a/docs/sphinx/source/contributing/style_guide.rst +++ b/docs/sphinx/source/contributing/style_guide.rst @@ -80,9 +80,11 @@ When specifying parameters and their units, please follow these guidelines: - Use the recommended parameter name and units listed in the :ref:`nomenclature` where applicable. - Enclose units in square brackets after the parameter description, e.g., ``Air temperature. [°C]``. - Use unicode superscripts symbols for exponents, e.g. ``m⁻²``. + - Numbers: ``⁰``, ``¹``, ``²``, ``³``, ``⁴``, ``⁵``, ``⁶``, ``⁷``, ``⁸``, ``⁹`` - Negative exponent: ``⁻`` - Degree symbol: ``°`` + - Link to a brief description in the :ref:`nomenclature` section if it exists, via the sphinx role ``:term:`glossary_term```. For example, to document ``dni`` use: .. code-block:: rst From 30b875aa506e8ef552d5fe8af8efbf7fa1083ed9 Mon Sep 17 00:00:00 2001 From: echedey-ls <80125792+echedey-ls@users.noreply.github.com> Date: Tue, 3 Dec 2024 19:44:59 +0000 Subject: [PATCH 13/13] Update v0.11.2.rst --- docs/sphinx/source/whatsnew/v0.11.2.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/sphinx/source/whatsnew/v0.11.2.rst b/docs/sphinx/source/whatsnew/v0.11.2.rst index 51549dd205..ad56f1744c 100644 --- a/docs/sphinx/source/whatsnew/v0.11.2.rst +++ b/docs/sphinx/source/whatsnew/v0.11.2.rst @@ -46,6 +46,8 @@ Documentation - `spectra` and `spectra_components` (:issue:`2150`, :pull:`2264`) +* Added a section in the style guide for parameter naming and units best practices. + See :ref:`documentation-units`. (:issue:`2205`, :pull:`2248`) Testing ~~~~~~~