From 228f3e99d89a4f200e782a71b02ab0425f5e1dc4 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Sat, 6 Aug 2022 20:55:16 +0100 Subject: Update docs to reflect the implementation of PEP 660 --- docs/userguide/pyproject_config.rst | 16 +++++++--------- docs/userguide/quickstart.rst | 19 +++++++++---------- 2 files changed, 16 insertions(+), 19 deletions(-) (limited to 'docs/userguide') diff --git a/docs/userguide/pyproject_config.rst b/docs/userguide/pyproject_config.rst index 709bf919..b1d4a4e3 100644 --- a/docs/userguide/pyproject_config.rst +++ b/docs/userguide/pyproject_config.rst @@ -7,10 +7,10 @@ Configuring setuptools using ``pyproject.toml`` files .. note:: New in 61.0.0 .. important:: - For the time being [#pep660-status]_, ``pip`` still might require a ``setup.py`` file - to support :doc:`editable installs ` [#setupcfg-caveats]_. - - A simple script will suffice, for example: + If compatibility with legacy builds or versions of tools that don't support + certain packaging standards (e.g. :pep:`517` or :pep:`660`), a simple ``setup.py`` + script can be added to your project [#setupcfg-caveats]_ + (while keeping the configuration in ``pyproject.toml``): .. code-block:: python @@ -214,12 +214,10 @@ however please keep in mind that all non-comment lines must conform with :pep:`5 .. rubric:: Notes -.. [#pep660-status] Editable install without ``setup.py`` will be supported in - future versions of ``setuptools``. Check https://github.com/pypa/setuptools/issues/2816 for detail. - .. [#setupcfg-caveats] ``pip`` may allow editable install only with ``pyproject.toml`` - and ``setup.cfg``. However, this behavior may not be consistent over various build - tools. Having a ``setup.py`` is still recommended if you rely on one of these tools. + and ``setup.cfg``. However, this behavior may not be consistent over various ``pip`` + versions and other packaging-related tools + (``setup.py`` is more reliable on those scenarios). .. [#entry-points] Dynamic ``scripts`` and ``gui-scripts`` are a special case. When resolving these metadata keys, ``setuptools`` will look for diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 24c71b8e..bf76f2c8 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -117,8 +117,7 @@ distributing into something that looks like the following (optional files marked with ``#``):: mypackage - ├── pyproject.toml - | # setup.cfg or setup.py (depending on the configuration method) + ├── pyproject.toml # and/or setup.cfg/setup.py (depending on the configuration method) | # README.rst or README.md (a nice description of your package) | # LICENCE (properly chosen license information, e.g. MIT, BSD-3, GPL-3, MPL-2, etc...) └── mypackage @@ -378,19 +377,18 @@ Here's how to do it:: pip install --editable . -This creates a link file in your interpreter site package directory which -associate with your source code. For more information, see :doc:`development_mode`. +See :doc:`development_mode` for more information. .. tip:: Prior to :ref:`pip v21.1 `, a ``setup.py`` script was required to be compatible with development mode. With late - versions of pip, ``setup.cfg``-only projects may be installed in this mode. + versions of pip, projects without ``setup.py`` may be installed in this mode. - If you are experimenting with :doc:`configuration using pyproject.toml `, - or have version of ``pip`` older than v21.1, you might need to keep a + If you have a version of ``pip`` older than v21.1 or is using a different + packaging-related tool that does not support :pep:`660`, you might need to keep a ``setup.py`` file in file in your repository if you want to use editable - installs (for the time being). + installs. A simple script will suffice, for example: @@ -400,8 +398,9 @@ associate with your source code. For more information, see :doc:`development_mod setup() - You can still keep all the configuration in :doc:`setup.cfg ` - (or :doc:`pyproject.toml `). + You can still keep all the configuration in + :doc:`pyproject.toml ` and/or + :doc:`setup.cfg ` Uploading your package to PyPI -- cgit v1.2.1