Merge docs on deprecated commands

Also add a not about modern ways of generating ``sdists`` and ``wheel``.

5 files changed, 45 insertions, 25 deletions

diff --git a/docs/conf.py b/docs/conf.py
index 159eedcd..a207c0d1 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -133,6 +133,7 @@ html_theme_options = {
 extensions += ['sphinx_reredirects']
 redirects = {
     "userguide/keywords": "/deprecated/changed_keywords.html",
+    "userguide/commands": "/deprecated/commands.html",
 }
 
 # Add support for inline tabs
diff --git a/docs/deprecated/commands.rst b/docs/deprecated/commands.rst
index e632e550..89acef85 100644
--- a/docs/deprecated/commands.rst
+++ b/docs/deprecated/commands.rst
@@ -1,3 +1,46 @@
+===============================
+Running ``setuptools`` commands
+===============================
+
+Historically, ``setuptools`` allowed running commands via a ``setup.py`` script
+at the root of a Python project, as indicated in the examples below::
+
+    python setup.py --help
+    python setup.py --help-commands
+    python setup.py --version
+    python setup.py sdist
+    python setup.py bdist_wheel
+
+You could also run commands in other circumstances:
+
+* ``setuptools`` projects without ``setup.py`` (e.g., ``setup.cfg``-only)::
+
+   python -c "import setuptools; setup()" --help
+
+* ``distutils`` projects (with a ``setup.py`` importing ``distutils``)::
+
+   python -c "import setuptools; with open('setup.py') as f: exec(compile(f.read(), 'setup.py', 'exec'))" develop
+
+That is, you can simply list the normal setup commands and options following the quoted part.
+
+.. warning::
+   On recent versions of ``setuptools`` running commands via ``python setup.py``
+   is considered **deprecated** (and should be avoided).
+
+   If you want to create :term:`sdist <Source Distribution (or "sdist")>` or :term:`wheel`
+   distributions the recommendation is to use the command line tool provided by :pypi:`build`::
+
+       pip install build  # needs to be installed first
+
+       python -m build  # builds both sdist and wheel
+       python -m build --sdist
+       python -m build --wheel
+
+   Build will automatically download ``setuptools`` and build the package in an
+   isolated environment. You can also specify specific versions of
+   ``setuptools``, by setting the :doc:`build requirements in pyproject.toml
+   </build_meta>`.
+
 -----------------
 Command Reference
 -----------------
diff --git a/docs/deprecated/index.rst b/docs/deprecated/index.rst
index ea9069ec..0ea66cf6 100644
--- a/docs/deprecated/index.rst
+++ b/docs/deprecated/index.rst
@@ -22,4 +22,4 @@ objectives.
     distutils/index
     distutils-legacy
     functionalities
-    running_commands
+    commands
diff --git a/docs/deprecated/running_commands.rst b/docs/deprecated/running_commands.rst
deleted file mode 100644
index 8d4ca93f..00000000
--- a/docs/deprecated/running_commands.rst
+++ /dev/null
@@ -1,23 +0,0 @@
-Running ``setuptools`` commands
-===============================
-
-Historically, ``setuptools`` allowed running commands via a ``setup.py`` script
-at the root of a Python project, as indicated in the examples below::
-
-    python setup.py --help
-    python setup.py --help-commands
-    python setup.py --version
-    python setup.py sdist
-    python setup.py bdist_wheel
-
-You could also run commands in other circumstances:
-
-* ``setuptools`` projects without ``setup.py`` (e.g., ``setup.cfg``-only)::
-
-   python -c "import setuptools; setup()" --help
-
-* ``distutils`` projects (with a ``setup.py`` importing ``distutils``)::
-
-   python -c "import setuptools; with open('setup.py') as f: exec(compile(f.read(), 'setup.py', 'exec'))" develop
-
-That is, you can simply list the normal setup commands and options following the quoted part.
diff --git a/docs/userguide/index.rst b/docs/userguide/index.rst
index d5d150af..f8bef013 100644
--- a/docs/userguide/index.rst
+++ b/docs/userguide/index.rst
@@ -34,7 +34,6 @@ Contents
     extension
     declarative_config
     pyproject_config
-    commands
     miscellaneous
 
 ---