[DOC]: params & units guidelines in contributing page (#2248)

* Fix external link that can be an internal cross reference

* Update style_guide.rst

* Minor improvements to docs

* Update style_guide.rst

* Update style_guide.rst

* Update style_guide.rst

* Update style_guide.rst

Co-Authored-By: RDaxini <[email protected]>

* Update docs/sphinx/source/contributing/style_guide.rst

Co-authored-by: RDaxini <[email protected]>

* Update docs/sphinx/source/contributing/style_guide.rst

Co-authored-by: Adam R. Jensen <[email protected]>

* Apply suggestions from code review

Co-authored-by: Adam R. Jensen <[email protected]>

* Fix link variables_style_rules -> nomenclature

Co-Authored-By: Adam R. Jensen <[email protected]>

* Fix bulleted list (hopefully 🙏 )

* Update v0.11.2.rst

---------

Co-authored-by: RDaxini <[email protected]>
Co-authored-by: Adam R. Jensen <[email protected]>

Author: 3 people

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
 <https://learn.scientific-python.org/development/tutorials/dev-environment/>`_
-is a good reference for virtual environments. The pvlib-python `installation
-user guide <https://pvlib-python.readthedocs.io/en/stable/user_guide/
-installation.html#set-up-a-virtual-environment>`_ also provides instructions on
+is a good reference for virtual environments. The pvlib-python
+:ref:`installation guide <setupenvironment>` also provides instructions on
 setting up a virtual environment. If this is your first pull request, don't
 worry about using a virtual environment.

docs/sphinx/source/contributing/style_guide.rst

@@ -70,6 +70,29 @@ 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 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
+
+      dni : numeric
+          Direct normal irradiance, see :term:`dni`. [Wm⁻²]
+
+
 .. _reference_style:
 
 References

docs/sphinx/source/reference/tracking.rst

@@ -3,9 +3,6 @@
 Tracking
 ========
 
-Functions
----------
-
 .. autosummary::
    :toctree: generated/
 

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/

docs/sphinx/source/whatsnew/v0.11.2.rst

@@ -51,6 +51,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`)
 * Added a example to :py:func:`~pvlib.pvsystem.retrieve_sam` docstring to
   demonstrate how to retrieve a database from the SAM repo. (:pull:`2313`)