From 24a1fca6207a46928647e7c8e766b117be8bdaf4 Mon Sep 17 00:00:00 2001 From: anshurajbisoyi98-ctrl Date: Sun, 4 Oct 2026 22:32:20 +0530 Subject: [PATCH 1/2] Document module-level constants --- docs/sphinx/source/conf.py | 3 +- docs/sphinx/source/reference/constants.rst | 48 +++++++++++++++++++ docs/sphinx/source/reference/index.rst | 1 + .../reference/pv_modeling/temperature.rst | 5 +- docs/sphinx/source/whatsnew/v0.16.2.rst | 3 ++ pvlib/albedo.py | 19 ++++++++ pvlib/atmosphere.py | 9 ++++ 7 files changed, 84 insertions(+), 4 deletions(-) create mode 100644 docs/sphinx/source/reference/constants.rst diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py index 90c2f0a3a5..2e5e59176f 100644 --- a/docs/sphinx/source/conf.py +++ b/docs/sphinx/source/conf.py @@ -74,7 +74,8 @@ # Enable hover tooltips hoverxref_auto_ref = True hoverxref_roles = [ - "class", "meth", "func", "ref", "term", "obj", "mod", "data" + "class", "meth", "func", "ref", "term", "obj", "mod", "data", + "const" ] hoverxref_role_types = dict.fromkeys(hoverxref_roles, "tooltip") hoverxref_domains = ["py"] diff --git a/docs/sphinx/source/reference/constants.rst b/docs/sphinx/source/reference/constants.rst new file mode 100644 index 0000000000..3b1041456d --- /dev/null +++ b/docs/sphinx/source/reference/constants.rst @@ -0,0 +1,48 @@ +.. currentmodule:: pvlib + +######### +Constants +######### + +This page documents module-level constants that are useful when configuring +pvlib models. Constants used by a specific model are also linked from that +model's reference page. + +Albedo +====== + +.. currentmodule:: pvlib.albedo + +.. autodata:: SURFACE_ALBEDOS + :annotation: + +.. autodata:: WATER_COLOR_COEFFS + :annotation: + +.. autodata:: WATER_ROUGHNESS_COEFFS + :annotation: + +Airmass and atmosphere +====================== + +.. currentmodule:: pvlib.atmosphere + +.. autodata:: APPARENT_ZENITH_MODELS + :annotation: + +.. autodata:: TRUE_ZENITH_MODELS + :annotation: + +.. autodata:: AIRMASS_MODELS + :annotation: + +.. autodata:: HELLMANN_SURFACE_EXPONENTS + :annotation: + +Temperature +=========== + +.. currentmodule:: pvlib.temperature + +.. autodata:: TEMPERATURE_MODEL_PARAMETERS + :annotation: diff --git a/docs/sphinx/source/reference/index.rst b/docs/sphinx/source/reference/index.rst index 8a990ac923..8ec675e174 100644 --- a/docs/sphinx/source/reference/index.rst +++ b/docs/sphinx/source/reference/index.rst @@ -8,6 +8,7 @@ API reference :maxdepth: 2 classes + constants solarposition clearsky airmass_atmospheric diff --git a/docs/sphinx/source/reference/pv_modeling/temperature.rst b/docs/sphinx/source/reference/pv_modeling/temperature.rst index 4c0c7c596b..1d0cb3dbe2 100644 --- a/docs/sphinx/source/reference/pv_modeling/temperature.rst +++ b/docs/sphinx/source/reference/pv_modeling/temperature.rst @@ -23,6 +23,5 @@ PV temperature models Temperature Model Parameters ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. currentmodule:: pvlib.temperature -.. autodata:: TEMPERATURE_MODEL_PARAMETERS - :annotation: +The available temperature model parameter sets are documented in +:doc:`../constants`. diff --git a/docs/sphinx/source/whatsnew/v0.16.2.rst b/docs/sphinx/source/whatsnew/v0.16.2.rst index f704525a12..ba489890d9 100644 --- a/docs/sphinx/source/whatsnew/v0.16.2.rst +++ b/docs/sphinx/source/whatsnew/v0.16.2.rst @@ -23,6 +23,8 @@ Enhancements Documentation ~~~~~~~~~~~~~ +* Add a reference page documenting useful module-level constants. (:issue:`2096`) + Testing ~~~~~~~ @@ -43,3 +45,4 @@ Maintenance Contributors ~~~~~~~~~~~~ +* Anshu Raj Bisoyi (:ghuser:`anshurajbisoyi98-ctrl`) diff --git a/pvlib/albedo.py b/pvlib/albedo.py index 2dca47ef3d..ba83284ff6 100644 --- a/pvlib/albedo.py +++ b/pvlib/albedo.py @@ -25,6 +25,13 @@ 'dirty steel': 0.08, 'sea': 0.06, } +"""Typical albedo values indexed by ground surface type. + +Values are used by :py:func:`pvlib.irradiance.get_ground_diffuse` and can +also be passed to :py:class:`pvlib.pvsystem.PVSystem` using ``surface_type``. +The cited sources for the values are listed in the ``get_ground_diffuse`` +documentation. +""" WATER_COLOR_COEFFS = { 'clear_water_no_waves': 0.13, @@ -34,6 +41,12 @@ 'green_water_ripples_up_to_2.5cm': 0.22, 'muddy_water_no_waves': 0.19 } +"""Water color coefficients for :py:func:`inland_water_dvoracek`. + +The keys are surface-condition names accepted by that function. Values are +empirically determined coefficients from the reference listed in its +documentation. +""" WATER_ROUGHNESS_COEFFS = { 'clear_water_no_waves': 0.29, @@ -43,6 +56,12 @@ 'green_water_ripples_up_to_2.5cm': 0.7, 'muddy_water_no_waves': 0.29 } +"""Water wave-roughness coefficients for :py:func:`inland_water_dvoracek`. + +The keys are surface-condition names accepted by that function. Values are +empirically determined coefficients from the reference listed in its +documentation. +""" def inland_water_dvoracek(solar_elevation, surface_condition=None, diff --git a/pvlib/atmosphere.py b/pvlib/atmosphere.py index 95401ff3ba..4802cba853 100644 --- a/pvlib/atmosphere.py +++ b/pvlib/atmosphere.py @@ -9,8 +9,11 @@ APPARENT_ZENITH_MODELS = ('simple', 'kasten1966', 'kastenyoung1989', 'gueymard1993', 'gueymard2003', 'pickering2002') +"""Relative-airmass model names that use apparent solar zenith angles.""" TRUE_ZENITH_MODELS = ('youngirvine1967', 'young1994') +"""Relative-airmass model names that use true solar zenith angles.""" AIRMASS_MODELS = APPARENT_ZENITH_MODELS + TRUE_ZENITH_MODELS +"""All model names accepted by :py:func:`get_relative_airmass`.""" def pres2alt(pressure): @@ -639,6 +642,12 @@ def angstrom_alpha(aod1, lambda1, aod2, lambda2): 'neutral_air_above_human_inhabited_areas': 0.34, 'stable_air_above_human_inhabited_areas': 0.60, } +"""Hellmann power-law exponents indexed by atmospheric and surface condition. + +These values are used by :py:func:`windspeed_powerlaw` when ``surface_type`` +is provided instead of an explicit exponent. The references and a summary +table are in that function's documentation. +""" def windspeed_powerlaw(wind_speed_reference, height_reference, From 4e153cf97eda5657ce26d216c52073b99067e1bf Mon Sep 17 00:00:00 2001 From: anshurajbisoyi98-ctrl Date: Mon, 5 Oct 2026 19:28:00 +0530 Subject: [PATCH 2/2] docs: place constants near related reference pages --- docs/sphinx/source/conf.py | 3 +- .../source/reference/airmass_atmospheric.rst | 18 +++++++ docs/sphinx/source/reference/constants.rst | 48 ------------------- docs/sphinx/source/reference/index.rst | 1 - .../source/reference/irradiance/other.rst | 13 +++++ .../reference/pv_modeling/temperature.rst | 7 ++- docs/sphinx/source/whatsnew/v0.16.2.rst | 4 +- 7 files changed, 40 insertions(+), 54 deletions(-) delete mode 100644 docs/sphinx/source/reference/constants.rst diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py index 2e5e59176f..96074a0d39 100644 --- a/docs/sphinx/source/conf.py +++ b/docs/sphinx/source/conf.py @@ -74,8 +74,7 @@ # Enable hover tooltips hoverxref_auto_ref = True hoverxref_roles = [ - "class", "meth", "func", "ref", "term", "obj", "mod", "data", - "const" + "class", "meth", "func", "ref", "term", "obj", "mod", "data", "const" ] hoverxref_role_types = dict.fromkeys(hoverxref_roles, "tooltip") hoverxref_domains = ["py"] diff --git a/docs/sphinx/source/reference/airmass_atmospheric.rst b/docs/sphinx/source/reference/airmass_atmospheric.rst index be3f47b65d..26cd681d1c 100644 --- a/docs/sphinx/source/reference/airmass_atmospheric.rst +++ b/docs/sphinx/source/reference/airmass_atmospheric.rst @@ -3,6 +3,19 @@ Airmass and atmospheric models ============================== +.. currentmodule:: pvlib.atmosphere + +.. autodata:: APPARENT_ZENITH_MODELS + :annotation: + +.. autodata:: TRUE_ZENITH_MODELS + :annotation: + +.. autodata:: AIRMASS_MODELS + :annotation: + +.. currentmodule:: pvlib + .. autosummary:: :toctree: generated/ @@ -19,3 +32,8 @@ Airmass and atmospheric models atmosphere.angstrom_aod_at_lambda atmosphere.angstrom_alpha atmosphere.windspeed_powerlaw + +.. currentmodule:: pvlib.atmosphere + +.. autodata:: HELLMANN_SURFACE_EXPONENTS + :annotation: diff --git a/docs/sphinx/source/reference/constants.rst b/docs/sphinx/source/reference/constants.rst deleted file mode 100644 index 3b1041456d..0000000000 --- a/docs/sphinx/source/reference/constants.rst +++ /dev/null @@ -1,48 +0,0 @@ -.. currentmodule:: pvlib - -######### -Constants -######### - -This page documents module-level constants that are useful when configuring -pvlib models. Constants used by a specific model are also linked from that -model's reference page. - -Albedo -====== - -.. currentmodule:: pvlib.albedo - -.. autodata:: SURFACE_ALBEDOS - :annotation: - -.. autodata:: WATER_COLOR_COEFFS - :annotation: - -.. autodata:: WATER_ROUGHNESS_COEFFS - :annotation: - -Airmass and atmosphere -====================== - -.. currentmodule:: pvlib.atmosphere - -.. autodata:: APPARENT_ZENITH_MODELS - :annotation: - -.. autodata:: TRUE_ZENITH_MODELS - :annotation: - -.. autodata:: AIRMASS_MODELS - :annotation: - -.. autodata:: HELLMANN_SURFACE_EXPONENTS - :annotation: - -Temperature -=========== - -.. currentmodule:: pvlib.temperature - -.. autodata:: TEMPERATURE_MODEL_PARAMETERS - :annotation: diff --git a/docs/sphinx/source/reference/index.rst b/docs/sphinx/source/reference/index.rst index 8ec675e174..8a990ac923 100644 --- a/docs/sphinx/source/reference/index.rst +++ b/docs/sphinx/source/reference/index.rst @@ -8,7 +8,6 @@ API reference :maxdepth: 2 classes - constants solarposition clearsky airmass_atmospheric diff --git a/docs/sphinx/source/reference/irradiance/other.rst b/docs/sphinx/source/reference/irradiance/other.rst index ebeecbce9f..988128f62a 100644 --- a/docs/sphinx/source/reference/irradiance/other.rst +++ b/docs/sphinx/source/reference/irradiance/other.rst @@ -3,6 +3,19 @@ Other ----- +.. currentmodule:: pvlib.albedo + +.. autodata:: SURFACE_ALBEDOS + :annotation: + +.. autodata:: WATER_COLOR_COEFFS + :annotation: + +.. autodata:: WATER_ROUGHNESS_COEFFS + :annotation: + +.. currentmodule:: pvlib + .. autosummary:: :toctree: ../generated/ diff --git a/docs/sphinx/source/reference/pv_modeling/temperature.rst b/docs/sphinx/source/reference/pv_modeling/temperature.rst index 1d0cb3dbe2..06632c6dc3 100644 --- a/docs/sphinx/source/reference/pv_modeling/temperature.rst +++ b/docs/sphinx/source/reference/pv_modeling/temperature.rst @@ -23,5 +23,8 @@ PV temperature models Temperature Model Parameters ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The available temperature model parameter sets are documented in -:doc:`../constants`. + +.. currentmodule:: pvlib.temperature + +.. autodata:: TEMPERATURE_MODEL_PARAMETERS + :annotation: diff --git a/docs/sphinx/source/whatsnew/v0.16.2.rst b/docs/sphinx/source/whatsnew/v0.16.2.rst index ba489890d9..7653d893bd 100644 --- a/docs/sphinx/source/whatsnew/v0.16.2.rst +++ b/docs/sphinx/source/whatsnew/v0.16.2.rst @@ -23,7 +23,8 @@ Enhancements Documentation ~~~~~~~~~~~~~ -* Add a reference page documenting useful module-level constants. (:issue:`2096`) +* Document useful module-level constants on the existing reference pages near + the related functions. (:pull:`2884`) Testing @@ -46,3 +47,4 @@ Contributors ~~~~~~~~~~~~ * Anshu Raj Bisoyi (:ghuser:`anshurajbisoyi98-ctrl`) +* Chen Yi (:ghuser:`chenyi6758-source`)