Change Variables and Symbols page into a Glossary of terms

[RDaxini]

• [X] Partially addresses #1421 (comment)
• [X] I am familiar with the contributing guidelines
• [ ] ~Tests added~
• [ ] ~Updates entries in docs/sphinx/source/reference for API changes.~
• [x] 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`).
• [X] New code is fully documented. Includes numpydoc compliant docstrings, examples, and comments where necessary.
• [x] Pull request is nearly complete and ready for detailed review.
• [x] 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.

https://github.com/pvlib/pvlib-python/blob/cbe4cc5a8bb3bb529f2dd885aebcd527fedbbc63/docs/sphinx/source/user_guide/variables_style_rules.rst?plain=1#L15-L25

[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?

[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

[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.

[RDaxini]

@IoannisSifnaios thanks for reviewing. I was thinking it'd be better to keep the scope of this PR focused on creating the glossary. DNI was expanded as an example (definition+link in function docs). I agree the others need updating, but I think that deciding how best to define each term / groups of terms might be better addressed in a separate PR. Happy to revisit this if you or anyone else thinks otherwise

[RDaxini]

is pointing to CPython's glossary: https://docs.python.org/3/glossary.html#glossary

Well spotted The other links worked fine and the _ didn't solve the problem for that link so I have changed the label from glossary to pvlib-glossary. Should be working now

[RDaxini]

I created #2284 to keep track of additional suggestions and address the comments from @IoannisSifnaios and @AdamRJensen (thanks for the suggestions)

Is deciding the name the only task remaining? From @IoannisSifnaios's definition, nomenclature sounds like the most technically accurate. Terminology makes me think more of words/phrases, but we have abbreviations and initialisms. That might just be my own inaccurate subjective impression though. I guess the four options now are:

Nomenclature, Variables and Symbols, Glossary, Terminology

How do we decide?

[cwhanse]

Nomenclature, Variables and Symbols, Glossary, Terminology

I'm OK with any of these.

How do we decide?

Sometimes the PR originator just chooses what color to paint the bikeshed.

[RDaxini]

Sometimes the PR originator just chooses what color to paint the bikeshed.

So much pressure 👀 Let's go with nomenclature! It's a mouthful, but I get the impression it's the most accurate. It's also widely used, including in many journals, so it should be familiar to most if not all users.

[RDaxini]

Will merge later today if no objections are raised by then

I'm still happy to make changes to any aspect if necessary, anyone please feel free to leave a comment 👍🏽

[kandersolar]

Thanks @RDaxini and all other participants! It's fun to see this idea finally implemented :)