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. diff --git a/docs/sphinx/source/contributing/style_guide.rst b/docs/sphinx/source/contributing/style_guide.rst index 6c53a27572..4eea571eda 100644 --- a/docs/sphinx/source/contributing/style_guide.rst +++ b/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 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/ diff --git a/docs/sphinx/source/whatsnew/v0.11.2.rst b/docs/sphinx/source/whatsnew/v0.11.2.rst index 49a1121c17..13dfc70e2e 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`) * Added a example to :py:func:`~pvlib.pvsystem.retrieve_sam` docstring to demonstrate how to retrieve a database from the SAM repo. (:pull:`2313`)