[DOC] PEP 621 - pyproject.toml vs setup.cfg

Summary

Hello,

As a newcomer to the python packaging world I was redirected from python.org to the setuptools documentation because python recommended it as the first choice for packaging. I had a quick read through the documentation and see that there are three different files for specifying project metadata/settings setup.py (for legacy projects - to be deprecated and kept to a bare minimum), setup.cfg (as I understood from the docs, some sort of successor of setup.py but with no code execution) and finally pyproject.toml. On the Configuring setuptools using pyproject.toml files page, the documentation mentions that since PEP 621 the python community has adopted the pyproject.toml as the go-to config file for specifying distribution/project metadata/settings. I therefore am left a bit confused as to what the use case is for the setup.cfg file and I did not feel like the documentation properly explained this. There is a separate page for Configuring setuptools with setup.cfg files but it doesn't address the overlap/difference between the two. I was therefore hoping that the experts in this community could clarify this and potentially have a separate page in the documentation (e.g. setup.cfg vs pyproject.toml) describing:

• The difference between the two and which use cases they serve
• Whether they should coexist or whether newer and older projects should aim to migrate to one of them as a result of PEP 621
• A much clearer (black and white) recommendation on what the ideal or python recommended way is of defining a project's configuration

I had a quick scan and search of the GitHub issues to see if this had been brought up before but got no hits on my search so apologies if this is a dupe.

Note: I could have made this a discussion but specifically chose to opt for an issue because I felt an improvement to the docs was necessary for clarity's sake.

Looking forward to hearing from the experts!
YVC

OS / Environment

N/A

Additional Information

For newbies like myself and potentially also intermediate/advanced developers, this clarity would hopefully ensure we are all going in the same direction in terms of the future of python packaging. :)

Code of Conduct

• I agree to follow the PSF Code of Conduct

Start with the “Configuring setuptools using pyproject.toml files” and “Configuring setuptools with setup.cfg files” pages, then review PEP 621 and the related 20-comment discussion. Document the differences, coexistence and migration guidance, and a clear recommendation for new and existing projects; the issue is done when these questions are answered consistently in the documentation.