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
~~~~~~~