Change Variables and Symbols page into a Glossary of terms

[RDaxini]

• Partially addresses Docstring parameter descriptions are somewhat redundant and inconsistent #1421 (comment)
• I am familiar with the contributing guidelines
• Tests added
• Updates entries in docs/sphinx/source/reference for API changes.
• Adds description and name entries in the appropriate "what's new" file in docs/sphinx/source/whatsnew for all changes. Includes link to the GitHub Issue with :issue:`num` or this Pull Request with :pull:`num`. Includes contributor name and/or GitHub username (link with :ghuser:`user`).
• New code is fully documented. Includes numpydoc compliant docstrings, examples, and comments where necessary.
• Pull request is nearly complete and ready for detailed review.
• Maintainer: Appropriate GitHub Labels (including remote-data) and Milestone are assigned to the Pull Request and linked Issue.

The glossary would replace the variables and symbols page. This is a limited example. Links:
Glossary
Function (see parameters surface_tilt and dni, and second paragraph in docstring)

Points to discuss: see this comment

---

Note:

• Took the liberty of alphabetizing the list since I did not see a logical order in the original
• Added/updated dni and surface_tilt definition to show example enhancements (linked to the example function)

Generally, I think adding/updating definitions (description, units, etc.) and adding/removing new/duplicate variables (#1421, #1253) probably requires a case-by-case discussion so I have not gone further here save for the two examples

[AdamRJensen]

Irradiation is energy (e.g., Wh/m^2) whereas irradiance is power (e.g., W/m^2). I think it's better to use irradiance

[RDaxini]

Thoughts on retaining any of the following text from variables_style_rules.rst before deleting the file? I haven't reviewed each link to verify it is an optimal source of information, but each link is still working and, overall, I think it's nice to include general educational content via external links. I am in favour of copying this over to the new page.

pvlib-python/docs/sphinx/source/user_guide/variables_style_rules.rst

Lines 15 to 25 in cbe4cc5

	For a definition and further explanation on the variables, common symbols and units refer to the following sources:
	* `IEC 61724-1:2017 -- Photovoltaic system performance - Part 1: Monitoring <https://webstore.iec.ch/publication/33622>`_ section: 3 -- Terms and definitions; the Indian Standard referencing the withdrawn earlier global IEC standard IEC 61724:1998 is available online: `IS/IEC 61724 (1998) <https://archive.org/details/gov.in.is.iec.61724.1998>`_ and can provide relevant contents.
	* Explanation of Solar irradiation and solar geometry by `SoDa Service <http://www.soda-pro.com/home>`_
	* `Acronyms, Terminology and Units <https://www.soda-pro.com/help/general/acronyms-terminology-and-units>`_
	* `Plane orientations and radiation components <https://www.soda-pro.com/help/general/plane-orientations-and-radiation-components>`_
	* `Time references <https://www.soda-pro.com/help/general/time-references>`_
	.. note:: These further references might not use the same terminology as *pvlib*. But the physical process referred to is the same.

[cwhanse]

I think its worth keeping the SodaPro references. We could drop the IEC 61724 links.

[echedey-ls]

A random thought, without any intentions: maybe instead of splitting and creating a whole new page, both of them could be put into the same one.

[kandersolar]

If the old page is being removed, then these references need to be updated:

$ git grep -n -F "variables_style_rules"
docs/sphinx/source/contributing/style_guide.rst:16::ref:`variables_style_rules`. We could be better about consistency.
docs/sphinx/source/index.rst:29:There is a :ref:`variable naming convention <variables_style_rules>` to
docs/sphinx/source/user_guide/index.rst:18:   variables_style_rules
docs/sphinx/source/user_guide/variables_style_rules.rst:1:.. _variables_style_rules:
docs/sphinx/source/user_guide/variables_style_rules.rst:9:   :file: ../../../../pvlib/data/variables_style_rules.csv
docs/sphinx/source/user_guide/weather_data.rst:86:into standard pvlib names (see :ref:`variables_style_rules`).
docs/sphinx/source/whatsnew/v0.3.0.txt:50:    * :ref:`variables_style_rules` (:issue:`102`)
pvlib/iotools/midc.py:196:    :ref:`variables_style_rules`.

[RDaxini]

If the old page is being removed, then these references need to be updated:

$ git grep -n -F "variables_style_rules"
docs/sphinx/source/contributing/style_guide.rst:16::ref:`variables_style_rules`. We could be better about consistency.
docs/sphinx/source/index.rst:29:There is a :ref:`variable naming convention <variables_style_rules>` to
docs/sphinx/source/user_guide/index.rst:18:   variables_style_rules
docs/sphinx/source/user_guide/variables_style_rules.rst:1:.. _variables_style_rules:
docs/sphinx/source/user_guide/variables_style_rules.rst:9:   :file: ../../../../pvlib/data/variables_style_rules.csv
docs/sphinx/source/user_guide/weather_data.rst:86:into standard pvlib names (see :ref:`variables_style_rules`).
docs/sphinx/source/whatsnew/v0.3.0.txt:50:    * :ref:`variables_style_rules` (:issue:`102`)
pvlib/iotools/midc.py:196:    :ref:`variables_style_rules`.

@kandersolar done, except for the 0.3.0 whatsnew entry. Anything needed there? Doesn't make sense to change the reference to "glossary", but should the :ref:`` be removed since the link won't work anyway (a warning is probably generated somewhere), or add something to say the page was removed in 11.2, or just leave it?

[echedey-ls]

@RDaxini minor comments down below, feel free to discard any of them.

[v0.3.0 whatsnew entry] should the :ref:`` be removed since the link won't work anyway

I would strive to not have any warnings in the docs - that's noise when reviewing. Plain code formatting is good for me.

LGTM, loving these improvements on documentation 😋

[AdamRJensen]

The terms Nomenclature or Terminology seem to be more correct than Glossary, as the list includes both terms and symbols/variables. Glossary I believe should only contain terms/definitions.

Terminology seems preferred to me as it's more easily understandable to non-native speakers.

[RDaxini]

The terms Nomenclature or Terminology seem to be more correct than Glossary, as the list includes both terms and symbols/variables. Glossary I believe should only contain terms/definitions.

Terminology seems preferred to me as it's more easily understandable to non-native speakers.

I don't mind "glossary", but I'm not opposed to changing the name. Just another thought: how about going back to the old name then, "Variables and Symbols"? I don't have a strong preference

[IoannisSifnaios]

Looks good overall! I left one or two comments. Regarding the name of the section, I also agree that Nomenclature (assigning of a word or phrase to a particular object, event, or property) would be a more suitable term than Glossary (terms that are either newly introduced, uncommon, or specialized)

[IoannisSifnaios]

Is there a reason why DNI has an extensive explanation of what it is (including units) while the other irradiances don't? I kind of like the idea of reporting the unit that each term is (usually) measured in pvlib.

[IoannisSifnaios]

Here the unit is mentioned in text. Should it be [°] instead?

[IoannisSifnaios]

Again maybe try to be consistent on whether we report the units and how

[AdamRJensen]

I don't mind "glossary", but I'm not opposed to changing the name. Just another thought: how about going back to the old name then, "Variables and Symbols"? I don't have a strong preference

I would be ok with either "Terminology" or "Variables and Symbols".

[echedey-ls]

I don't really like "Variables and Symbols"; to be precise it's more about "Common Parameters" - but I agree "Terminology" is good if it gets expanded to other terms in the future.

An small side-note, the supposed link in https://pvlib-python--2234.org.readthedocs.build/en/2234/contributing/style_guide.html (first section "Code Style", second paragraph, second sentence) to the glossary is pointing to CPython's glossary: https://docs.python.org/3/glossary.html#glossary . It may be due to the crossreference at the top of the file missing an underscore at the beginning.