Functions to consider making private

[kandersolar]

I noticed we have several functions that don't have pages in our API reference, but are also not private (name doesn't start with _):

• pvlib.iotools.midc.format_index
• pvlib.iotools.midc.format_index_raw
• pvlib.iotools.srml.format_index
• pvlib.iotools.srml.map_columns
• pvlib.iotools.surfrad.format_index
• pvlib.scaling.latlon_to_xy
• everything in pvlib.spa except solar_position, transit_sunrise_sunset, earthsun_distance, and calculate_deltat
  • Note that these functions lack real pages but do have stub entries here: https://pvlib-python.readthedocs.io/en/stable/reference/generated/pvlib.spa.html

I propose we make all these functions private (add a leading underscore to their names). I doubt they get any meaningful amount of use, so I wouldn't bother with a deprecation for any of them.

[cwhanse]

Only pvlib.spa.calculate_deltat has a hyperlink.

[kandersolar]

Only pvlib.spa.calculate_deltat has a hyperlink.

Unless I'm mistaken, the calculation in calculate_deltat is not actually part of the SPA, despite living in spa.py. I wonder if it should be moved from solarposition.py. If we did that, then none of the functions in spa.py would really be user-facing (they are all supposed to be used by the wrappers in solarposition.py) and I guess the entire module could be made private (pvlib._spa).

[wholmgren]

I've gone back and forth on this and ultimately I guess it's ok. It seems unnecessarily hostile to users that actually went to the effort to read source code, and we want more of those users rather than antagonizing the few that we have. I've used some of these functions in my own code, but I'm not the typical user and I can update it if I need to. And I'd like to see spa moved to its own package, but who wants to support that? Which is the point, isn't it?

[kandersolar]

My thinking is that (with the possible exception of pvlib.tools) functions should either (1) have a stable interface and be fully documented in the sphinx docs, or (2) be an implementation detail and marked private with the underscore prefix. My motivation here isn't so much about maintenance/support burden, it's just about moving these functions into one of those two options and out of the no man's land they're in right now. So I'd be fine with bringing the SPA presence in the sphinx docs up to snuff instead of making them private like #1769 does.

I do think the non-SPA functions listed above should probably be private though.

[kandersolar]

The SPA-related changes in #1769 are now reverted. Now it only changes the other functions listed above. I'd rather improve the SPA docs in a separate PR.

[kandersolar]

On closer inspection, I realized scaling.latlon_to_xy was intended to be public, it just wasn't listed in the sphinx docs. #1769 now lists it instead of making it private.