[Docs] section: (setup.py vs setup.cfg) -> update with: (setup.py vs pyproject.toml)?

[VladimirFokow]

Summary

Related to: #3683

I propose to update this section: Transitioning from setup.py to setup.cfg (introduced by commit b2af2ea)

It says:

we are transitioning into a full-fledged setup.cfg to declare your package information instead of running setup()

• haven't we already "transitioned from setup.py"?
• only to setup.cfg? What about pyproject.toml?
• some context about setup.cfg and pyproject.toml would be nice to have

Additional Information

As a new user of setuptools, it was difficult for me to know which one is newer: pyproject.toml or setup.cfg.

Code of Conduct

• I agree to follow the PSF Code of Conduct

[VladimirFokow]

I learned:

• pyproject.toml still isn't guaranteed to do some functionality which setup.cfg can. So a black-and-white solution can't be recommendable for everyone. Upd: correction

• the approach setuptools would like to take is to eventually use a single declarative format (pyproject.toml) instead of maintaining 2 (pyproject.toml / setup.cfg).

• Using pyproject.toml, however, imposes constraints (specially around dynamic) to the build. Some users may not be comfortable with these constraints

• setup.cfg will probably be supported for a long time

So this kind of context would be useful in the docs.

Links:

in #3518:

tools doing static analysis do not support import hooks

in #3214:

the approach setuptools would like to take is to eventually use a single declarative format (pyproject.toml) instead of maintaining 2 (pyproject.toml/setup.cfg)

we are in no rush to deprecated setup.cfg

For the time being there it is not in the horizon of events to drop setup.cfg completely. setup.cfg has not even been deprecated yet.

Even if we eventually drop the custom parsing, chances are it will still keep working via "transpiling" it to pyproject.toml syntax for a long time, until it is safe to assume everyone moved out of it.