[Docs] Clarify expected interface for running distutils.commands

Summary

I am the maintainer of py2exe and I am in the process of migrating it from distutils to setuptools. While reading the new documentation, I found out this extremely useful page that carefully explains how to add a new command and even new keywords for the setup() method, effectively mimicking what has been possible up to now with distutils. If this API is supposed to be actively supported in the future, changes on py2exe would most likely be relatively minimal.

However, at the end of the very same page, under Final Remarks there is this sentence:

Directly calling python setup.py ... is considered a deprecated practice. You should not add new commands to setuptools expecting them to be run via this interface.

which seems to contradict the point of the whole page. I think I am missing something here: what is then the expected way to run a distutils.commands entry point? Do you plan to discontinue the python setup.py ... command interface?

Thanks for this clarification and for maintaining setuptools.

OS / Environment

No response

Additional Information

The linked page should clarify what is the command line interface that should be used to run commands added to setuptools via the supported distutils.commands entry point.

Code of Conduct

• I agree to follow the PSF Code of Conduct

Start by reading the linked setuptools extension documentation, especially the command example and Final Remarks. Review the unresolved question about the supported interface for running distutils.commands entry points, then update the page so the expected command-line workflow and status of python setup.py are explicit.