diff --git a/changelog.d/3371.doc.rst b/changelog.d/3371.doc.rst new file mode 100644 index 0000000000..7e49c13907 --- /dev/null +++ b/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. diff --git a/docs/conf.py b/docs/conf.py index 159eedcd71..a207c0d129 100644 --- a/docs/conf.py +++ b/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 diff --git a/docs/userguide/commands.rst b/docs/deprecated/commands.rst similarity index 92% rename from docs/userguide/commands.rst rename to docs/deprecated/commands.rst index e632e550b3..e287ab8f07 100644 --- a/docs/userguide/commands.rst +++ b/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 ``. + + If you want to create :term:`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 + `. + + 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 ----------------- diff --git a/docs/deprecated/index.rst b/docs/deprecated/index.rst index ea9069ecb2..0ea66cf644 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 8d4ca93fc1..0000000000 --- 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 d5d150af2e..f8bef0137f 100644 --- a/docs/userguide/index.rst +++ b/docs/userguide/index.rst @@ -34,7 +34,6 @@ Contents extension declarative_config pyproject_config - commands miscellaneous ---