centrally defined abbreviations for units with special formatting

[RDaxini]

• Closes Standarizing pvlib typesetting of units - standarization for common variables? #2205
• 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.

Additional context
Suggested replacements:
|wm2| -> Wm⁻²
|wm2nm1| -> Wm⁻²nm⁻¹
|degc| -> °C
|deg| -> °
Note: click shift+\ to type |

Includes some common units but the current list just gives an idea of what is possible. Feel free to recommend inclusions/exclusions/modifications. See here for example usage (solar_azimuth, dhi, dni_extra)

I also tried:
|^-1| -> ⁻¹
|^-2| -> ⁻²
to create some individual superscripts for more flexible applications (e.g. in atmosphere.pres2alt we have ms⁻²) but this did not render correctly in the docs. Is this a problem / does anyone have a suggestion to resolve this?

ps ignore the branch name, nothing to do with latex

[RDaxini]

@echedey-ls do you have any ideas about this?
None of these attempts worked (apart from using :math:, but no-one wants that) 😂

I was not confident about the latex commands since the docs are html, not pdf, but I thought creating the new roles would work, or at the very least just typing out the superscript manually with <sup> </sup> would work,,, but no

[echedey-ls]

I haven't had a look at your commits, but the best thing that comes to my mind is the following:

• Add a prolog rst_prolog in conf.py with a substitution pattern
  • https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#substitutions
  • https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#substitution-definitions
  • https://docutils.sourceforge.io/docs/ref/rst/directives.html#replacement-text
• Substitutions could be:
  • .. |W/m^2| replace:: [Wm⁻²]
  • and the same for all common units pvlib uses; be aware there are a lot of combinations you could make use of, in this case I put brackets so in a docstring parameter we avoid using pipes and brackets all together.
  • this is both readable through help and RTD
  • in a paragraph, you will do:

    poa_global: plane-of-array global irradiance. |W/m^2|.
    

    which should render as:
    poa_global: plane-of-array global irradiance. [Wm⁻²].

IDK at what point I've become your sphinx reference guy, but I don't dislike that hahahaha.

[echedey-ls]

I think this PR is now a nice example (thx Dax) of how this would look like: https://pvlib-python--2209.org.readthedocs.build/en/2209/reference/generated/pvlib.irradiance.get_total_irradiance.html

Params dhi and dni_extra.

[RDaxini]

@echedey-ls credit to you for suggesting the substitutions method! I was not aware of that functionality in sphinx.
(there you go, this is why you're the sphinx reference guy 😂)

[RDaxini]

conf.py seems to have a lot of linting issues, for example # not being followed by a space, which I guess in those cases is since the # is followed by an optional line of code. How did conf.py pass the Flake8 Linter test in the past? Should I resolve these linting issues or leave them?

[kandersolar]

How did conf.py pass the Flake8 Linter test in the past?

The flake8 job is configured to only check lines that are near other lines that have changed in the PR, and we don't change conf.py very often :)

Should I resolve these linting issues or leave them?

My two cents: reviewing PRs is already hard enough without extra "clutter" of unrelated formatting changes. Best to do them in a separate PR where improved formatting is the objective.

[RDaxini]

Closed, see comment