`transit_sunrise_sunset`: seems as a public function, not in public docs?

pvlib / pvlib-python

A set of documented functions for simulating the performance of photovoltaic energy systems.

https://pvlib-python.readthedocs.io

BSD 3-Clause "New" or "Revised" License

1.19k stars 998 forks source link

`transit_sunrise_sunset`: seems as a public function, not in public docs? #2255

Open echedey-ls opened 2 weeks ago

echedey-ls commented 2 weeks ago

Describe the bug https://github.com/pvlib/pvlib-python/blob/cbe4cc5a8bb3bb529f2dd885aebcd527fedbbc63/pvlib/spa.py#L1106

Personally, I don't find any signs that it may be a private function. However, it does not appear in the webpage:

https://pvlib-python.readthedocs.io/en/stable/search.html?q=transit_sunrise_sunset

Well it's not true: it appears here https://pvlib-python.readthedocs.io/en/stable/reference/generated/pvlib.spa.html I wasn't around when pvlib.spa didn't get documented, so seeing it's not the only undocumented function, maybe it was deliberate?

Expected To see its documentation on ReadTheDocs.

Versions:

pvlib.__version__: 0.11.0

cwhanse commented 2 weeks ago

In v0.1 when this function was added the documents didn't have the auto-built the API reference pages. Omission was probably to avoid cluttering the solarposition.py module page and only list the most significant functions.

echedey-ls commented 2 weeks ago

I understand why it didn't get included at that time. For the current status of pvlib, is it desired to publicize it or not? I feel it is a well-documented function that may compete with pvlib.location.Location.get_sun_rise_set_transit. At least that one, I can't speak for the rest of functions. Consider this issue as a potential discussion-opener for that.

cwhanse commented 1 week ago

I don't see any downside to adding this function to the API documentation.

AdamRJensen commented 1 week ago

Agreed, a PR to include it is welcomed 😄