issue #2314 updating doc #2382
issue #2314 updating doc #2382
Conversation
There was a problem hiding this comment.
Thanks for working on this issue.
Made a couple of suggestions following an initial scan through. It might be helpful to review the contributing guidelines, in particular the specific page on documentation and style (e.g. regarding units and definitions)
We could get into some of the more involved aspects of this PR afterwards.
| * `aoi`: The angle-of-incidence of direct irradiance onto the | ||
| rotated panel surface. [degrees] | ||
| rotated panel surface. |
There was a problem hiding this comment.
| rotated panel surface. | |
| rotated panel surface. [°] |
The units should not be deleted from the docs. It's important to state the units for each variable. In this case, we could change from the text "degrees" to the symbol, but not delete it entirely.
| * `surface_tilt`: The angle between the panel surface and the earth | ||
| surface, accounting for panel rotation. [degrees] | ||
| surface, accounting for panel rotation. |
There was a problem hiding this comment.
Please refer to the variable defiitions in the glossary, for example for surface_tilt: https://pvlib-python.readthedocs.io/en/latest/user_guide/nomenclature.html#term-surface_tilt
You can also link definitions on the docs page to glossary definitions using the :term: role, for example:
| surface, accounting for panel rotation. | |
| surface, accounting for panel rotation. See :term:`surface_tilt`. |
You can find other similar guidelines on the contributing page
| positive cross-axis tilt if the tracker axes plane slopes down to the | ||
| west. Use :func:`~pvlib.tracking.calc_cross_axis_tilt` to calculate | ||
| ``cross_axis_tilt``. [degrees] | ||
| Ground coverage ratio, the ratio of row width to row spacing. |
There was a problem hiding this comment.
I think the more comprehensive definition has value. Perhaps finding a midpoint for the docs then having a more comprehensive definition on the glossary page is an option?
|
@bandish1304 another suggestion, you can tag the issue number where the xxx is in the issue description, and change the title to something that summarizes the issue you are fixing. |
docs/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.