Deprecate modelchain.basic_chain

[kandersolar]

• [ ] Closes #xxxx
• I am familiar with the contributing guidelines
• Tests added
• Updates entries in docs/sphinx/source/reference for API changes.
• Adds description and name entries in the appropriate "what's new" file in docs/sphinx/source/whatsnew for 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`).
• New code is fully documented. Includes numpydoc compliant docstrings, examples, and comments where necessary.
• Pull request is nearly complete and ready for detailed review.
• Maintainer: Appropriate GitHub Labels and Milestone are assigned to the Pull Request and linked Issue.

See #1385 (comment)

Do we remove functions from the API listing at deprecation or at removal? SingleAxisTracker and some other deprecated things are currently listed, so I've not removed basic_chain here.

[mikofski]

I think there is some Sphinx “deprecated” directive, and also like “new since vX.Y” — I think we should use that:
https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html

[kandersolar]

Yes there is! Our nice @deprecated decorator actually automatically inserts it into the docstring, so no need for us to do it manually:

pvlib-python/pvlib/_deprecation.py

Lines 308 to 310 in f86d71d

	new_doc = (('\n.. deprecated:: %(since)s'
	'\n %(message)s\n\n' %
	{'since': since, 'message': message}) + old_doc)

Result:

and

[wholmgren]

Do we remove functions from the API listing at deprecation or at removal? SingleAxisTracker and some other deprecated things are currently listed, so I've not removed basic_chain here.

Yes, I think we should and that we have in the past.

[cwhanse]

Do we remove functions from the API listing at deprecation or at removal?

I favor removal at removal. If a user gets a deprecation message, they may want to look at the old documentation as part of their migration work. Removing it from the API listing makes it a bit harder to find.

[cwhanse]

Thanks @kanderso-nrel My preference for retaining documentation until removal is not a blocker if the majority feels otherwise.

[wholmgren]

ModelChain.with_sapm is a more direct replacement for basic_chain, so should we also/alternatively recommend that to users in the what's new and deprecation message?