Docstring parameter descriptions are somewhat redundant and inconsistent

[kandersolar]

Is your feature request related to a problem? Please describe.
Conventions like pvlib's definition of surface_tilt and surface_azimuth are documented somewhat haphazardly in docstring parameter descriptions. This is objectionable in that it is redundant (same description appears in many places) and inconsistent (not all descriptions are the same for a particular parameter). For example many functions in pvlib.irradiance have parameter descriptions like this:

pvlib-python/pvlib/irradiance.py

Lines 553 to 555 in df1c56e

	Surface tilt angles in decimal degrees. Tilt must be >=0 and
	<=180. The tilt angle is defined as degrees from horizontal
	(e.g. surface facing up = 0, surface facing horizon = 90).

while some others have this:

pvlib-python/pvlib/irradiance.py

Line 329 in df1c56e

Panel tilt from horizontal. [degree]

Describe the solution you'd like
I'm proposing we convert the "Variables and Symbols" page into a sphinx glossary. Much like how :py:func: links to function definitions, sphinx glossaries allow you to link terms to their definitions using :term:`surface_tilt`. So a glossary like this:

.. glossary::

   surface_tilt
      Collector surface tilt angle, measured upwards from horizontal.
      Zero tilt means a horizontal surface (facing directly upwards).
      See also :term:`surface_azimuth`.

   ...

would let all surface_tilt docstring parameter descriptions reduce to something like this:

surface_tilt : numeric
    See :term:`surface_tilt` [degrees]

Describe alternatives you've considered
The downside I see to extracting and centralizing this information is that the gallery definitions are only immediately accessible in the built sphinx docs, so help(pvlib.irradiance.klucher) and pvlib.irradiance.klucher? will be less useful (or, depending on your viewpoint, less cluttered). So there is an argument to be made that centralizing this information is not a net gain and we should continue including it in the docstrings themselves.

Additional context
#1253 is vaguely relevant

[mikofski]

A compromise is short description (for REPL) + “for more detail description see :glossary:term“ or something like that. Then you have best of both worlds maybe?

[AdamRJensen]

I have a number of times noticed the issue of inconsistent naming of the same variable in different places. So I'm definitely in favor of implementing sphinx glossary. However, I also share @mikofski's point that it would be nice to have a combination.

Perhaps for simple stuff like surface_tilt it is fine to only defer to the glossary as the name is descriptive and intuitive.

However, for less intuitive variables, such as acronyms, I would prefer a small description. For example, many users might not know what aoi stands for, so in this case, I would propose a combination like this:

aoi : numeric
    Angle of incidence, see :term:`aoi`

Then, the range, convention, and a more elaborate description can be provided in the glossary.

[RDaxini]

Is anyone currently working on this? If not, I am very interested in taking on this work. I have a few projects running currently though so I might be a bit slow, but I guess since this is unresolved since 2022 we'd be okay with a few months more? 😅

[cwhanse]

Can we convert the "Variables and Symbols" page to a glossary as a first step? I am hesitant to remove the descriptions from docstrings. For those browsing the code, using the command line to look at documentation, or reviewing changes, having AOI spelled out along with "see :term:aoi" would be a little frustrating.

[RDaxini]

Can we convert the "Variables and Symbols" page to a glossary as a first step?

Sounds reasonable to me 👍🏾