Standarizing pvlib typesetting of units - standarization for common variables?

[echedey-ls]

Is your feature request related to a problem? Please describe.
As of now, units in the whole documentation are written with the own developer style, and there is no place that suggests which units should be used in any case.

Current typesetting includes:

1. LaTeX like markup, e.g., W/m^2 (in https://pvlib-python.readthedocs.io/en/latest/reference/generated/pvlib.irradiance.dirint.html)
2. Mathjax rendering using the Sphinx math role, e.g., :math:`W/m^2` (in https://pvlib-python.readthedocs.io/en/latest/reference/generated/pvlib.irradiance.get_ground_diffuse.html)
3. Unicode plaintext using superscript numbers, optionally superscript dash to avoid the slash; e.g., W/m² or Wm⁻², Wm⁻²nm⁻¹ (in https://pvlib-python.readthedocs.io/en/latest/reference/generated/pvlib.spectrum.spectrl2.html)

(I can't find some comment in a review of my PRs or so talking about alternatives and views with @kandersolar and @AdamRJensen )

On one side new/current contributors don't have a clear guideline on what to do when writing units. Both in API docs and examples. On the other side, switching between docs and seeing different ways of writing it may confuse inexperienced users.
And it looks a bit crappy that each dev sticks to it's own style.

Now the topic moves to Variables and Symbols. I think that units that make a convention have a spot there, and can be used to template units out of there too. E.g.:

• eta_inv | inverter efficiency <> in % or in [0,1]? (and the same goes for many of them)

Normalizing what units shall be used for each variable guarantees pvlib is a toolbox of tools that fit together.

Describe the solution you'd like
I personally think an homogeneous typesetting is beneficial for the project. And if I had to choose, I don't like cluttering the view with extra characters like ^2 when ² exists, so I'm +1 for homogenizing and changing to option 3. I somewhat agree with @RDaxini on using superscript minus sign ⁻.

Describe alternatives you've considered

1. Proposing and pushing and agenda to adopt a complete PVlib Enhancement Proposals (PVEP) system the same way Python has PEPs, Numpy NEPs and Matplotlib MEPs, then convincing everyone that option 3 is the right path, because it is.
2. Not doing anything 🙄

Additional context
When a decision on this is agreed, this would make for a good set of Easy and How-To-Contribute series of PRs for newcomers, conferences and workshops.

[cwhanse]

+1 to putting units with the variable names.

As far as typesetting, my only complaint about option 3 is that I don't know how to type the superscript characters. I could learn but in reality I will end up searching the code for a function with that symbol, and copying it.

[RDaxini]

+1 to putting units with the variable names.

+1

As far as typesetting, my only complaint about option 3 is that I don't know how to type the superscript characters. I could learn but in reality I will end up searching the code for a function with that symbol, and copying it.

is it possible to define commands like you can in a latex file? For example, in latex, you can set something like \wm2 to be equal to Wm⁻². If that's possible in pvlib we could easily have a central set of definitions like this along with however we want the units to be rendered in the docs. It would be faster and more efficient when it comes to actually writing the docs too.

ps. full transparency: copy/pasting is all I was ever doing with my superscripts anyway 😂

[echedey-ls]

Given there already are discussions on breaking the contributing page into multiple sections (#2200), my take on this would be adding all the unicode superscripts to a page dedicated to docs and just write it all with them, for simplicity and also reading them through the help().

+1 to putting units with the variable names.

Cross-referencing #1421

[AdamRJensen]

+1 on standardization

I can support subscripts as long as we have them written down somewhere that is easy to copy from.

I think what needs to be done is to have a template function, which shows the preferred way of writing units, variable naming, etc.

[AdamRJensen]

+1 to using subscripts as along as we have a place where they can easily be copied from.

-1 on using special commands to do some kind of formatting (increases maintenance burden and doesn't seem any simpler for new users)

Overall, I think we should create a template function that demonstrates the preferred way to do citations, units, parameter definitions, etc.

[RDaxini]

I can support subscripts as long as we have them written down somewhere that is easy to copy from.

#2209 --- we can define some easy-to-type abbreviations e.g. |wm2| for Wm⁻² so no need to locate and copy/paste special text

Does that count as a special command...? I think | should be on most if not all keyboards with the \ key, right? Users could still copy and paste the units directly if they wanted though, even if typing something like |wm2| was available at the same time.

I think what needs to be done is to have a template function, which shows the preferred way of writing units, variable naming, etc.

Agreed. I was thinking that in the split contributing page (#2210) we could have a style guide section where all information on existing (e.g. PEP 8) and new (references, units, etc.) styles could be explained. A template could easily be included here for illustration.

[echedey-ls]

Does that count as a special command...?

@RDaxini , I'm afraid they are somewhat commands.

I agree with @AdamRJensen that these substitution patterns are a burden for newcomers; also that they clutter the view and understanding of the functions via help(). I would just go with your formatting of units via manual substitution if you prefer to call it that way. That is usually Control+H to replace things in editors or using tools like ripgrep if your editor does not provide it (VSCode gang 😎 ).

To address @cwhanse concern, I would say the best choice is to update the contributing section on docs, with superscripts, rather than come up with some special way of interpreting and handling them in sphinx.

[RDaxini]

Does that count as a special command...?

@RDaxini , I'm afraid they are somewhat commands.

After a little while I understood what was meant by command, I misunderstood at first 😅

I agree with @AdamRJensen that these substitution patterns are a burden for newcomers; also that they clutter the view and understanding of the functions via help().

Seems like no-one disagrees on this here so I'll close #2209 and we can move forward with adding a simple small table/list into the new style guide section from which users can easily copy/paste, and be informed of the style rule.
Shall I open a PR or would you like to @echedey-ls ?

[echedey-ls]

Shall I open a PR or would you like to @echedey-ls ?

I don't really mind, but yeah, I can manage that. I think I will also try to do the docstring template in the same PR. I can't tell when I'll open it - expect some delay.

[RDaxini]

also try to do the docstring template in the same PR. I can't tell when I'll open it - expect some delay.

Cool. If you want to split anything, just let me know. Happy to help

[adriesse]

BTW, in ipython you can enter things like \beta<TAB> to get unicode characters.