From 7cd56d3c92be8fc45b029eb4c01b581d8dcf84f0 Mon Sep 17 00:00:00 2001
From: Anderson Bravalheri <andersonbravalheri@gmail.com>
Date: Thu, 24 Mar 2022 14:09:51 +0000
Subject: Add back notes about editable install and pyproject metadata

On further examination, `pip` seems to fail if `setup.py` is missing.
---
 docs/userguide/pyproject_config.rst | 12 ++++++++++++
 docs/userguide/quickstart.rst       | 18 +++++++++++++++++-
 2 files changed, 29 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/userguide/pyproject_config.rst b/docs/userguide/pyproject_config.rst
index a139fa73..3988db2f 100644
--- a/docs/userguide/pyproject_config.rst
+++ b/docs/userguide/pyproject_config.rst
@@ -12,6 +12,18 @@ Configuring setuptools using ``pyproject.toml`` files
    ``setuptools`` via ``pyproject.toml`` files is still experimental and might
    change (or be removed) in future releases.
 
+.. important::
+   For the time being, ``pip`` still might require a ``setup.py`` file
+   to support :doc:`editable installs <pip:cli/pip_install>`.
+
+   A simple script will suffice, for example:
+
+   .. code-block:: python
+
+       from setuptools import setup
+
+       setup()
+
 Starting with :pep:`621`, the Python community selected ``pyproject.toml`` as
 a standard way of specifying *project metadata*.
 ``Setuptools`` has adopted this standard and will use the information contained
diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst
index 71d44370..3af8aaa8 100644
--- a/docs/userguide/quickstart.rst
+++ b/docs/userguide/quickstart.rst
@@ -343,7 +343,23 @@ associate with your source code. For more information, see :doc:`development_mod
 
     Prior to :ref:`pip v21.1 <pip:v21-1>`, a ``setup.py`` script was
     required to be compatible with development mode. With late
-    versions of pip, any project may be installed in this mode.
+    versions of pip, ``setup.cfg``-only projects may be installed in this mode.
+
+    If you are experimenting with :doc:`configuration using <pyproject_config>`,
+    or have version of ``pip`` older than v21.1, 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).
+
+    A simple script will suffice, for example:
+
+    .. code-block:: python
+
+        from setuptools import setup
+
+        setup()
+
+    You can still keep all the configuration in :doc:`setup.cfg </userguide/declarative_config>`
+    (or :doc:`pyproject.toml </userguide/pyproject_config>`).
 
 
 Uploading your package to PyPI
-- 
cgit v1.2.1