📝 Document setup.cfg-only projects

2 files changed, 43 insertions, 0 deletions

diff --git a/docs/requirements.txt b/docs/requirements.txt
index bc27165b..e82df49c 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,4 +1,5 @@
 sphinx!=1.8.0
+pygments-github-lexers==0.0.5
 rst.linker>=1.9
 jaraco.packaging>=6.1
 
diff --git a/docs/setuptools.txt b/docs/setuptools.txt
index d214ca99..3a2028ce 100644
--- a/docs/setuptools.txt
+++ b/docs/setuptools.txt
@@ -2195,6 +2195,48 @@ Metadata and options are set in the config sections of the same name.
 
 * Unknown keys are ignored.
 
+setup.cfg-only projects
+=======================
+
+.. versionadded:: 40.9.0
+
+If ``setup.py`` is missing from the project directory when a PEP 517
+build is invoked, ``setuptools`` emulates a dummy ``setup.py`` file containing
+only a ``setuptools.setup()`` call.
+
+.. note::
+
+    PEP 517 doesn't support editable installs so this is currently
+    incompatible with ``pip install -e .``.
+
+This means that you can have a Python project with all build configuration
+specified in ``setup.cfg``, without a ``setup.py`` file, if you **can rely
+on** your project always being built by a PEP 517/518 compatible frontend.
+
+To use this feature:
+
+* Specify build requirements and PEP 517 build backend in
+  ``pyproject.toml``.
+  For example:
+
+  .. code-block:: toml
+
+      [build-system]
+      requires = [
+        "setuptools >= 40.9.0",
+        "wheel",
+      ]
+      build-backend = "setuptools.build_meta"
+
+* Use a PEP 517 compatible build frontend, such as ``pip >= 19`` or ``pep517``.
+
+  .. warning::
+
+      As PEP 517 is new, support is not universal, and frontends that
+      do support it may still have bugs. For compatibility, you may want to
+      put a ``setup.py`` file containing only a ``setuptools.setup()``
+      invocation.
+
 
 Using a ``src/`` layout
 =======================