Docs: recommend using pip instead of setuptools

[humitos]

• mention pip is the recommended way
• mention setuptools is deprecated
• remove setuptools from the examples in favor of pip

Related #8659

---

📚 Documentation previews 📚

• User's documentation (docs): https://docs--9567.org.readthedocs.build/en/9567/

• Developer's documentation (dev): https://dev--9567.org.readthedocs.build/en/9567/

[ericholscher]

This is a good first step, but we should probably put the deprecation information somewhere? Seems like we should maybe have a page with a list, and the approximate date we expect to remove it?

[humitos]

@ericholscher Yes. I'm on board with creating a deprecation.rst page and list all the things we are deprecating there with deprecation and removal dates that we link from all these places. What is a good time frame for the final removal? 1, 2 or 3 months?

[ericholscher]

@humitos I think it will depend on the feature. Since this one was a documented default up until today, I think we probably want a reasonably long timeline. I'd say 3 months from when we send a PR/email to all effected projects, but even that seems aggressive for something that's not deprecated by the ecosystem.

[humitos]

I think it's deprecated already. Python's official documentation refers to it as "Legacy version" and also has a note at the top: https://docs.python.org/3/install/

[...] The entire distutils package has been deprecated and will be removed in Python 3.12. [...]

[humitos]

I'm merging this PR to move forward with the changes in the documentation and avoid new projects using legacy workflows. We can keep discussing the proper final removal of this feature and the creation of the deprecation.rst page in the next iteration. I think updating the documentation is a good first step.