[WIP] irradiance.py updates: glossary term links and units #2311
Conversation
pvlib/irradiance.py
Outdated
| The sky diffuse component of the solar radiation. [Wm⁻²] | ||
| The sky diffuse component of the solar radiation [Wm⁻²]. |
There was a problem hiding this comment.
Where are these periods supposed to go? Before or after the units? I see a mix in the docs. I've gone for after.
There was a problem hiding this comment.
The recently added documentation example featured the period before the units.
I think this probably deserves a vote, mostly just a final decision.
There was a problem hiding this comment.
The recently added documentation example featured the period before the units.
I think this probably deserves a vote, mostly just a final decision.
Ah I missed that.
Could react here?
👍 for after solar radiation [Wm⁻²]. ...
👎 for before solar radiation. [Wm⁻²] ...
When the units are at the end of the sentence, ie no subsequent text, either way looks fine. When there's text after the units, I think period after is better, so for consistency I just thought [Wm⁻²]. made sense. I don't feel too strongly either way though, but if someone else does then I'm happy just to follow that 😅 Edit: after encountering more examples while making modifications, I am now more strongly in favour of [Wm⁻²].
There was a problem hiding this comment.
Units before the period suggests that it's a member of the preceding sentence and should obey its grammatical structure. Consider this example from pvlib.temperature.sapm_cell:
pvlib-python/pvlib/temperature.py
Lines 72 to 73 in b50b56f
The unit could be confused as a parenthetical describing the thing before it (a height of 10 meters in this case), which of course is not the intended meaning.
Fundamentally I think the unit describes the parameter, not something in the parameter description text, and we are only including the unit immediately adjacent to the description because sphinx doesn't offer a more structured alternative. For example, in a different documentation system that represents parameters in tabular form, we might have chosen to have description and unit in separate columns. Since we don't actually have tables, all we can do is to put them next to each other. But I don't see why it makes sense to go a step further and include the units inside (instead of after) the description text.
Not sure that's convincing to others, but anyway I'm +1 to period before units.
|
I could modify the scope of this PR if we want to see some of the changes implemented in 11.2. I don't think these changes are urgent though so I'm also happy to keep working on it and merge the completed version in 11.3. Not sure what reviewers would prefer though--- on second thoughts many small revisions covering the entire |
pvlib/irradiance.py
Outdated
| The sky diffuse component of the solar radiation. [Wm⁻²] | ||
| The sky diffuse component of the solar radiation [Wm⁻²]. |
There was a problem hiding this comment.
The recently added documentation example featured the period before the units.
I think this probably deserves a vote, mostly just a final decision.
Co-authored-by: Adam R. Jensen <[email protected]>
…-python into irradiance_updates
| Diffuse horizontal irradiance. [Wm⁻²] | ||
| Diffuse horizontal irradiance. [Wm⁻²] See :term:`dhi`. | ||
|
|
||
| dni : numeric | ||
| Direct normal irradiance, see :term:`dni`. [Wm⁻²] | ||
|
|
||
| dni_extra : numeric | ||
| Extraterrestrial normal irradiance. [Wm⁻²] | ||
| Extraterrestrial normal irradiance, see :term:`dni_extra`. [Wm⁻²] |
There was a problem hiding this comment.
Any reason to choose one syntax over the other here?
Extraterrestrial normal irradiance, see :term:`dni_extra`. [Wm⁻²]
vs
Extraterrestrial normal irradiance. [Wm⁻²] See :term:`dni_extra`.
There was a problem hiding this comment.
I've come around to thinking the style is better if the unit is closely associated with the quantity name. In this case,
Extraterrestrial normal irradiance [Wm⁻²]. See :term:`dni_extra`
I deliberately put the period after the unit. I know we recently discussed that "point", but if I can, I'd like to change my vote to dotting after the unit.
I have long thought that using square brackets and putting the unit at the end of the description was some kind of readthedocs or markdown thing. It's clear now that it's just a style choice, and one that I think we can improve.
There was a problem hiding this comment.
I've come around to thinking the style is better if the unit is closely associated with the quantity name. In this case,
Extraterrestrial normal irradiance [Wm⁻²]. See :term:`dni_extra`I deliberately put the period after the unit. I know we recently discussed that "point", but if I can, I'd like to change my vote to dotting after the unit.
I have long thought that using square brackets and putting the unit at the end of the description was some kind of readthedocs or markdown thing. It's clear now that it's just a style choice, and one that I think we can improve.
I agree, I am still in favour of this style. However, I think it's been outvoted if @AdamRJensen's review counts as a thumbs down on this comment :/
@kandersolar I can't fault your logic here, but what would you do in this case? As for the example you gave, since height already has a units I don't think there could possibly be any confusion(?)
Tests addedUpdates entries indocs/sphinx/source/referencefor API changes.docs/sphinx/source/whatsnewfor 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`).remote-data) and Milestone are assigned to the Pull Request and linked Issue.Updating the units to superscript and linking key terms to their glossary page definitions.
Follow up PR(s): add some of these key terms into the glossary, enhance existing glossary term definitions (units and explanation)
Note: we can now view definition tooltips by hovering the cursor over the linked glossary term (context: #2290)