Docs: reflect removal of direct setup.py invocations

Author: sbidoul

docs/html/cli/pip.rst

@@ -77,7 +77,7 @@ when decision is needed.
 .. _`2-build-system-interface`:
 .. rubric:: Build System Interface
 
-This is now covered in :doc:`../reference/build-system/index`.
+This is now covered in :doc:`../reference/build-system`.
 
 .. _`General Options`:
 

docs/html/cli/pip_install.rst

@@ -255,7 +255,7 @@ This is now covered in :doc:`../topics/local-project-installs`.
 .. _`0-build-system-interface`:
 .. rubric:: Build System Interface
 
-This is now covered in :doc:`../reference/build-system/index`.
+This is now covered in :doc:`../reference/build-system`.
 
 .. _`pip install Options`:
 

docs/html/cli/pip_wheel.rst

@@ -28,7 +28,7 @@ Description
 .. _`1-build-system-interface`:
 .. rubric:: Build System Interface
 
-This is now covered in :doc:`../reference/build-system/index`.
+This is now covered in :doc:`../reference/build-system`.
 
 Differences to ``build``
 ------------------------

docs/html/reference/build-system/pyproject-toml.md renamed to docs/html/reference/build-system.md

@@ -1,9 +1,28 @@
-# `pyproject.toml`
+(build-interface)=
 
 ```{versionadded} 10.0
 
 ```
 
+```{versionchanged} 23.1
+The legacy interface where pip could invoke `setup.py install`
+in some circumstances was removed,
+in favor of the fallback behavior described below.
+```
+
+```{versionchanged} 25.3
+The legacy interface where pip could invoke `setup.py build_wheel` or
+`setup.py develop` in some circumstances was removed,
+in favor of the fallback behavior described below..
+```
+
+# Build System Interface
+
+When dealing with installable source distributions of a package, pip does not
+directly handle the build process for the package. This responsibility is
+delegated to "build backends" -- also known as "build systems". This means
+that pip needs an interface, to interact with these build backends.
+
 Modern Python packages can contain a `pyproject.toml` file, first introduced in
 {pep}`518` and later expanded in {pep}`517`, {pep}`621` and {pep}`660`.
 This file contains build system requirements and information, which are used by
@@ -96,16 +115,6 @@ For performing editable installs, pip will use {pep}`660`
 `build_wheel_for_editable` hook that has to be provided by the build backend.
 The wheels generated using this mechanism are not cached.
 
-```{admonition} Compatibility fallback
-If this hook is missing on the build backend _and_ there's a `setup.py` file
-in the project, pip will fallback to the legacy setup.py-based editable
-installation.
-
-This is considered a stopgap solution until setuptools adds support for
-{pep}`660`, at which point this functionality will be removed; following pip's
-regular {ref}`deprecation policy <Deprecation Policy>`.
-```
-
 ### Backend Configuration
 
 Build backends have the ability to accept configuration settings, which can
@@ -125,8 +134,7 @@ files.
 ## Build output
 
 It is the responsibility of the build backend to ensure that the output is
-in the correct encoding, as described in {pep}`517`. This likely involves
-dealing with [the same challenges as pip has for legacy builds](build-output).
+in the correct encoding, as described in {pep}`517`.
 
 ## Fallback Behaviour
 
@@ -138,7 +146,8 @@ https://setuptools.pypa.io/en/stable/userguide/quickstart.html#basic-use).
 ```
 
 If a project does not have a `pyproject.toml` file containing a `build-system`
-section, it will be assumed to have the following backend settings:
+section, and contains a `setup.py` it will be assumed to have the following
+backend settings:
 
 ```toml
 [build-system]

docs/html/reference/build-system/index.md

@@ -6,7 +6,7 @@ interoperability standards that pip utilises/implements.
 ```{toctree}
 :titlesonly:
 
-build-system/index
+build-system
 requirement-specifiers
 requirements-file-format
 installation-report

docs/html/reference/build-system/setup-py.md

@@ -109,7 +109,6 @@ and two {ref}`--find-links <install_--find-links>` locations:
 
 The options which can be applied to individual requirements are:
 
-- {ref}`--global-option <install_--global-option>`
 - {ref}`--config-settings <install_--config-settings>`
 - `--hash` (for {ref}`Hash-checking mode`)
 
@@ -150,30 +149,3 @@ You can now store sensitive data (tokens, keys, etc.) in environment variables
 and only specify the variable name for your requirements, letting pip lookup
 the value at runtime. This approach aligns with the commonly used
 [12-factor configuration pattern](https://12factor.net/config).
-
-
-## Influencing the build system
-
-```{danger}
-This disables the use of wheels (cached or otherwise). This could mean that builds will be slower, less deterministic, less reliable and may not behave correctly upon installation.
-
-This mechanism is only preserved for backwards compatibility and should be considered deprecated. A future release of pip may drop these options.
-```
-
-The `--global-option` option is used to pass options to `setup.py`.
-
-```{attention}
-These options are highly coupled with how pip invokes setuptools using the {doc}`../reference/build-system/setup-py` build system interface. It is not compatible with newer {doc}`../reference/build-system/pyproject-toml` build system interface.
-
-This is will not work with other build-backends or newer setup.cfg-only projects.
-```
-
-If you have a declaration like:
-
-    FooProject >= 1.2 --global-option="--no-user-cfg"
-
-The above translates roughly into running FooProject's `setup.py` script as:
-
-    python setup.py --no-user-cfg install
-
-Note that the only way of giving more than one option to `setup.py` is through multiple `--global-option` options.