[Docs] remove distutils legacy ref when setuptools docs are complete

[jacalata]

Documentation

https://docs.python.org/3/distutils/index.html has this disclaimer

This document is being retained solely until the setuptools documentation at https://setuptools.readthedocs.io/en/latest/setuptools.html independently covers all of the relevant information currently included here.

I couldn't find anywhere tracking progress towards having that coverage in setuptools docs, so that's the purpose of this issue. I'm not sure whether there needs to be a consensus, or how to make the decision to check off a chapter as fully replaced.

• 1. An Introduction to Distutils](https://docs.python.org/3/distutils/introduction.html)
• 2. Writing the Setup Script](https://docs.python.org/3/distutils/setupscript.html)
• 3. Writing the Setup Configuration File](https://docs.python.org/3/distutils/configfile.html)
• 4. Creating a Source Distribution](https://docs.python.org/3/distutils/sourcedist.html)
• 5 Creating Built Distributions](https://docs.python.org/3/distutils/builtdist.html)
• 6. Distutils Examples](https://docs.python.org/3/distutils/examples.html)
• 7. Extending Distutils](https://docs.python.org/3/distutils/extending.html)
• 8. Command Reference](https://docs.python.org/3/distutils/commandref.html)
• 9 API Reference](https://docs.python.org/3/distutils/apiref.html)

This issue can track work being done in the setuptools docs: pypa/setuptools#3401

[merwok]

Rather than pure deletion, I think the docs could be retained to avoid breaking all the external links, with a small explanation for the removal of the package and links to equivalent setutpools docs.

I think there are existing tickets about removing distutils, could you search for them and add links between this ticket and those ones?

[CAM-Gerlach]

Rather than pure deletion, I think the docs could be retained to avoid breaking all the external links, with a small explanation for the removal of the package and links to equivalent setutpools docs.

That's a good idea. distutils is removed completely from the stdlib in 3.12, what I will propose in a PR for 3.12 following your recommendations, is retaining the document and top-level sections headers to not break any links, add an admonition up top and messages to each section explaining distutils has been removed and linking to the up to date setuptools equivalents, but remove all the obsolete content, as it doesn't really belong here anymore and makes it much easier for users to miss or ignore the message (especially if deeplinked). And of course, users can always switch to an older Python version that includes distutils if they still actually need these docs (just like with any other removed module).

For previous maintained versions (3.11 and 3.10), the content can be retained as-is, but the messages redirecting users could be added, to help direct users to the Setuptools equivalents now rather than only when Python 3.12 is released and it is fully removed. To make merging straightforward (and also not block it on a final decision), I can drop a PR with this first (as well as one with the other docs changes for distutils removal), which can be backported, and then a followup PR only for 3.12 to remove all the obsolete section content.

A few sections don't have direct Setuptools equivalents, but this would give Setuptools a full year to decide whether they want to add the relevant section and link it here, move the existing section over to their docs and maintain it themselves, or leave it deliberately undocumented as internal implementation details. And of course, users could still switch to an older version to see them.

I think there are existing tickets about removing distutils, could you search for them and add links between this ticket and those ones?

#92584 (issue) and #99061 (PR)