[Docs] Improve documentation about migration from distutils

[abravalheri]

Summary of changes

• State that the local copy of distutils is active by default
• Recommend logging instead of distutils.log
• Link PEP 632 migration advice.

Closes

Pull Request Checklist

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

[matteius]

@abravalheri Hi again, now I am investigating build CI failures in requirementslib. It seems at some point before I was working on the project the build started failing with:

/home/matteius/requirementslib/.nox/coverage/lib/python3.9/site-packages/_distutils_hack/init.py:17: UserWarning: Distutils was imported before Setuptools, but importing Setuptools also replaces the distutils module in sys.modules. This may lead to undesirable behaviors or errors. To avoid these issues, avoid using distutils directly, ensure that setuptools is installed in the traditional way (e.g. not an editable install), and/or make sure that setuptools is always imported before distutils.

I was scratching my head for a while until I found this PR with the updated documentation, and I tried setting export SETUPTOOLS_USE_DISTUTILS=stdlib and it was like magic causing the builld to run again and see what the actual test failures are. I am wondering now what the work around would be like to use the new default behavior, if you have ideas? Also, I see where distutils is going away at some-point, so does that mean usage such as from setuptools.dist import Distribution, distutils is going to further break soon? Thanks for your insights!