docs: draft for plugin support with declarative config

[alvyjudy]

on #2155

Summary of changes

I have worked out a draft to document the plugin support features in setuptools that covers the following:

1. overview on making plugin for setuptools
2. how to register commands (declarative and setup script)
3. how to obtain parameters from the user's setup configuration (declarative and setup script)

Note that

1. the declarative style documented here uses the setup.cfg file and I haven't figured out how to do this with pyproject.toml
2. I have yet to test the examples given or make them self-contained
3. It doesn't explain how things work under the hood since I feel that should be in a separate document (e.g. developer guide)

If this seems to be on the right track I'll be happy to finalize it:)

Pull Request Checklist

• Changes have tests
• News fragment added in changelog.d. See documentation for details

[jaraco]

I'm not sure we want to advertise this functionality. Much of the ecosystem has moved away from extending distutils and instead focuses on creating protocols for tools to build packages. If this functionality is documented, it probably should have a more compelling example.

[jaraco]

IIUC, the most important part of what happens is the parsed value is set on the dist object.

[jaraco]

Rather than speak about "plugins" generally, I would describe "extending Setuptools commands" or similar.

[alvyjudy]

I might have misunderstood ticket #2155 or confused about the related context. Are the plugins we intend to describe best practice for not the ones I have documented in this file? Thanks in advance for clarifying that:)

[jaraco]

I might have misunderstood ticket #2155 or confused about the related context. Are the plugins we intend to describe best practice for not the ones I have documented in this file? Thanks in advance for clarifying that:)

#2155 mentions #1055, wherein a new entry point (setuptools.finalize_distribution_options) in #1877 was added. The purpose of #2155 is to ensure that behavior is featured prominently as part of the command plugin functionality. I didn't realize that maybe command extensions wasn't already documented.

Ultimately, what #2155 is asking is to capture that setup_keywords is discouraged in favor of setuptools.finalize_distribution_options hooks that set values from configuration files.

[jaraco]

I do apologize. The guidance in #2155 was pretty bad, and even as I'm reading it, I'm unsure what additional effort that ticket entailed. For now, I'm going to decline this PR and close #2155, as what's in master now is adequate.