Consider using computed docstrings

[kandersolar]

As mentioned by @wholmgren in https://github.com/pvlib/pvlib-python/issues/2326#issuecomment-2685685954, the new pvlib.iotools.psm4 functions have long, very similar docstrings, which may be improved by using computed docstrings:

If we go with the separate functions then I think we should venture into computed docstrings. Computed docstrings are now common in the pydata world but haven't yet been used in pvlib. The module is 800 lines and about half of those are minor permutations of a 100 line docstring - and this will only get worse if we mirror more of the NSRDB API.

Here are some breadcrumbs I found with a brief investigation:

• Some PyPI packages exist for this sort of thing: https://pypi.org/search/?q=docstring
• pandas uses this: https://github.com/pandas-dev/pandas/blob/main/pandas/util/_decorators.py#L342
• scipy uses this: https://github.com/scipy/scipy/blob/main/scipy/_lib/doccer.py
  • but not everyone likes it: https://github.com/scientific-python/summit-2024/issues/27

Some additional food for thought: do the docstrings have to be generated at import time (may not work with some IDEs as linked above, plus adds import overhead), or can we find some way to generate them once during package build or installation?

[markcampanelli]

Before adding complexity, I would ask “How often do these docstrings actually change?”