[Docs] Move command description to the deprecated practice section (#…

…3371)

changelog.d/3371.doc.rst

@@ -0,0 +1,3 @@
+Moved documentation from ``/userguide/commands`` to ``/depracted/commands``.
+This change was motived by the fact that running ``python setup.py`` directly is
+considered a deprecated practice.

docs/conf.py

@@ -133,6 +133,7 @@
 extensions += ['sphinx_reredirects']
 redirects = {
     "userguide/keywords": "/deprecated/changed_keywords.html",
+    "userguide/commands": "/deprecated/commands.html",
 }
 
 # Add support for inline tabs

docs/userguide/commands.rst → docs/deprecated/commands.rst

@@ -1,3 +1,59 @@
+===============================
+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::
+   While it is perfectly fine that users write ``setup.py`` files to configure
+   a package build (e.g. to specify binary extensions or customize commands),
+   on recent versions of ``setuptools``, running ``python setup.py`` directly
+   as a script is considered **deprecated**. This also means that users should
+   avoid running commands directly via ``python setup.py <command>``.
+
+   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>`.
+
+   If you want to install a package, you can use :pypi:`pip` or :pypi:`installer`::
+
+      pip install /path/to/wheel/file.whl
+      pip install /path/to/sdist/file.tar.gz
+      pip install .  # replacement for python setup.py install
+      pip install --editable .  # replacement for python setup.py develop
+
+      pip install installer  # nees to be installed first
+      python -m installer /path/to/wheel/file.whl
+
 -----------------
 Command Reference
 -----------------

docs/deprecated/index.rst

@@ -22,4 +22,4 @@ objectives.
     distutils/index
     distutils-legacy
     functionalities
-    running_commands
+    commands

docs/userguide/index.rst

@@ -35,7 +35,6 @@ Contents
     extension
     declarative_config
     pyproject_config
-    commands
     miscellaneous
 
 ---