From 61b941337ece67ef766b549c4147137988c4cdb7 Mon Sep 17 00:00:00 2001
From: Anderson Bravalheri <andersonbravalheri@gmail.com>
Date: Tue, 7 Jun 2022 18:11:00 +0100
Subject: [PATCH 1/7] Warn about 'tool.setuptool' instead of project metadata
 in pyproject.toml

---
 pytest.ini                         |  2 +-
 setuptools/config/pyprojecttoml.py | 15 ++++++++-------
 2 files changed, 9 insertions(+), 8 deletions(-)

diff --git a/pytest.ini b/pytest.ini
index 14c7e94c27..0be8d7e2ef 100644
--- a/pytest.ini
+++ b/pytest.ini
@@ -59,4 +59,4 @@ filterwarnings=
 	ignore:Distutils was imported before setuptools
 	ignore:Setuptools is replacing distutils
 
-	ignore:Support for project metadata in .pyproject.toml. is still experimental
+	ignore:Support for configuring .* in .pyproject.toml. is still experimental
diff --git a/setuptools/config/pyprojecttoml.py b/setuptools/config/pyprojecttoml.py
index 976eb0634c..ce5ad04d7a 100644
--- a/setuptools/config/pyprojecttoml.py
+++ b/setuptools/config/pyprojecttoml.py
@@ -94,12 +94,13 @@ def read_configuration(
     if not asdict or not (project_table or setuptools_table):
         return {}  # User is not using pyproject to configure setuptools
 
-    # TODO: Remove the following once the feature stabilizes:
-    msg = (
-        "Support for project metadata in `pyproject.toml` is still experimental "
-        "and may be removed (or change) in future releases."
-    )
-    warnings.warn(msg, _ExperimentalProjectMetadata)
+    if setuptools_table:
+        # TODO: Remove the following once the feature stabilizes:
+        msg = (
+            "Support for configuring `[tool.setuptools]` in `pyproject.toml` is still "
+            "experimental and may change in future releases."
+        )
+        warnings.warn(msg, _ExperimentalConfiguration)
 
     # There is an overall sense in the community that making include_package_data=True
     # the default would be an improvement.
@@ -413,7 +414,7 @@ def __exit__(self, exc_type, exc_value, traceback):
         return super().__exit__(exc_type, exc_value, traceback)
 
 
-class _ExperimentalProjectMetadata(UserWarning):
+class _ExperimentalConfiguration(UserWarning):
     """Explicitly inform users that `pyproject.toml` configuration is experimental"""
 
 

From 2734a357dad91dcddf3a8e4e5779c5e68da621eb Mon Sep 17 00:00:00 2001
From: Anderson Bravalheri <andersonbravalheri@gmail.com>
Date: Tue, 7 Jun 2022 22:16:34 +0100
Subject: [PATCH 2/7] Clarify warnings and notes in documentation about
 experimental pyproject.toml

---
 docs/userguide/dependency_management.rst | 23 ++++++-----------------
 docs/userguide/pyproject_config.rst      | 13 ++++++-------
 docs/userguide/quickstart.rst            | 14 ++++++--------
 3 files changed, 18 insertions(+), 32 deletions(-)

diff --git a/docs/userguide/dependency_management.rst b/docs/userguide/dependency_management.rst
index a35d7bfc53..f92e22c49f 100644
--- a/docs/userguide/dependency_management.rst
+++ b/docs/userguide/dependency_management.rst
@@ -75,7 +75,7 @@ finesse to it, let's start with a simple example.
             ],
         )
 
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml
 
     .. code-block:: toml
 
@@ -124,7 +124,7 @@ the Python version is older than 3.4. To accomplish this
             ],
         )
 
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml
 
     .. code-block:: toml
 
@@ -160,7 +160,7 @@ and only install it if the user is using a Windows operating system:
             ],
         )
 
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml
 
     .. code-block:: toml
 
@@ -215,7 +215,7 @@ optional PDF support and requires two other dependencies for it to work:
             },
         )
 
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml
 
     .. code-block:: toml
 
@@ -261,7 +261,7 @@ installed, it might declare the dependency like this:
             ...,
         )
 
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml
 
     .. code-block:: toml
 
@@ -361,7 +361,7 @@ This can be configured as shown in the example below.
         )
 
 
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml
 
     .. code-block:: toml
 
@@ -370,16 +370,5 @@ This can be configured as shown in the example below.
         requires-python = ">=3.6"
         # ...
 
-----
-
-.. rubric:: Notes
-
-.. [#experimental]
-   While the ``[build-system]`` table should always be specified in the
-   ``pyproject.toml`` file, support for adding package metadata and build configuration
-   options via the ``[project]`` and ``[tool.setuptools]`` tables is still
-   experimental and might change in future releases.
-   See :doc:`/userguide/pyproject_config`.
-
 
 .. _PyPI: https://pypi.org
diff --git a/docs/userguide/pyproject_config.rst b/docs/userguide/pyproject_config.rst
index 8558f5d79d..dcf284d5f3 100644
--- a/docs/userguide/pyproject_config.rst
+++ b/docs/userguide/pyproject_config.rst
@@ -4,13 +4,7 @@
 Configuring setuptools using ``pyproject.toml`` files
 -----------------------------------------------------
 
-.. note:: New in 61.0.0 (**experimental**)
-
-.. warning::
-   Support for declaring :doc:`project metadata
-   <PyPUG:specifications/declaring-project-metadata>` or configuring
-   ``setuptools`` via ``pyproject.toml`` files is still experimental and might
-   change in future releases.
+.. note:: New in 61.0.0
 
 .. important::
    For the time being, ``pip`` still might require a ``setup.py`` file
@@ -75,6 +69,11 @@ The ``project`` table contains metadata fields as described by
 Setuptools-specific configuration
 =================================
 
+.. warning::
+   Support for declaring configurations not standardized by :pep:`621`
+   (i.e.  the ``[tool.setuptools]`` table),
+   is still **experimental** and might change in future releases.
+
 While the standard ``project`` table in the ``pyproject.toml`` file covers most
 of the metadata used during the packaging process, there are still some
 ``setuptools``-specific configurations that can be set by users that require
diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst
index 9fcf09397d..923b1d4e1b 100644
--- a/docs/userguide/quickstart.rst
+++ b/docs/userguide/quickstart.rst
@@ -98,7 +98,7 @@ The following example demonstrates a minimum configuration
 
     See :doc:`/references/keywords` for more information.
 
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml
 
     .. code-block:: toml
 
@@ -260,7 +260,7 @@ The following configuration examples show how to accomplish this:
             }
         )
 
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml
 
     .. code-block:: toml
 
@@ -300,7 +300,7 @@ The example below show how to configure this kind of dependencies:
             # ...
         )
 
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml
 
     .. code-block:: toml
 
@@ -448,10 +448,8 @@ up-to-date references that can help you when it is time to distribute your work.
    supported in those files (e.g. C extensions).
 
 .. [#experimental]
-   While the ``[build-system]`` table should always be specified in the
-   ``pyproject.toml`` file, support for adding package metadata and build configuration
-   options via the ``[project]`` and ``[tool.setuptools]`` tables is still
-   experimental and might change in future releases.
-   See :doc:`/userguide/pyproject_config`.
+   Support for adding build configuration options via the ``[tool.setuptools]``
+   in the ``pyproject.toml`` file table is still experimental and might change
+   in future releases. See :doc:`/userguide/pyproject_config`.
 
 .. _PyPI: https://pypi.org

From 94ff0b480541b9ccc1799bbef32a4f65caa0fc75 Mon Sep 17 00:00:00 2001
From: Anderson Bravalheri <andersonbravalheri@gmail.com>
Date: Tue, 7 Jun 2022 22:26:05 +0100
Subject: [PATCH 3/7] Add news fragment

---
 changelog.d/3347.change.rst | 2 ++
 1 file changed, 2 insertions(+)
 create mode 100644 changelog.d/3347.change.rst

diff --git a/changelog.d/3347.change.rst b/changelog.d/3347.change.rst
new file mode 100644
index 0000000000..f0dac6b833
--- /dev/null
+++ b/changelog.d/3347.change.rst
@@ -0,0 +1,2 @@
+Changed warnings and documentation notes about *experimental* aspect of ``pyproject.toml`` configuration:
+now only the ``[tool.setuptools]`` table (and sub-tables) are considered experimental.

From 9c7163bc6030e546ba1133de823d0b4ac06a02d9 Mon Sep 17 00:00:00 2001
From: Anderson Bravalheri <andersonbravalheri@gmail.com>
Date: Thu, 16 Jun 2022 21:50:25 +0100
Subject: [PATCH 4/7] Change wording from *experimental* to *beta*

---
 changelog.d/3347.change.rst          |  3 ++-
 docs/userguide/datafiles.rst         | 20 ++++++++++----------
 docs/userguide/entry_point.rst       | 13 ++++---------
 docs/userguide/package_discovery.rst | 20 ++++++++++----------
 docs/userguide/pyproject_config.rst  |  4 ++--
 docs/userguide/quickstart.rst        | 14 +++++++-------
 pytest.ini                           |  2 +-
 setuptools/config/pyprojecttoml.py   | 11 ++++-------
 8 files changed, 40 insertions(+), 47 deletions(-)

diff --git a/changelog.d/3347.change.rst b/changelog.d/3347.change.rst
index f0dac6b833..b229981a66 100644
--- a/changelog.d/3347.change.rst
+++ b/changelog.d/3347.change.rst
@@ -1,2 +1,3 @@
 Changed warnings and documentation notes about *experimental* aspect of ``pyproject.toml`` configuration:
-now only the ``[tool.setuptools]`` table (and sub-tables) are considered experimental.
+now ``[pyproject]`` is a fully supported configuration interface, but the ``[tool.setuptools]`` table
+and sub-tables are still considered to be in **beta** stage.
diff --git a/docs/userguide/datafiles.rst b/docs/userguide/datafiles.rst
index 3a2ffbdf05..8501e95dc9 100644
--- a/docs/userguide/datafiles.rst
+++ b/docs/userguide/datafiles.rst
@@ -56,7 +56,7 @@ and you supply this configuration:
         include_package_data=True
     )
 
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml (**BETA**) [#beta]_
 
    .. code-block:: toml
 
@@ -137,7 +137,7 @@ data files:
             package_data={"mypkg": ["*.txt", "*.rst"]}
         )
 
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml (**BETA**) [#beta]_
 
    .. code-block:: toml
 
@@ -210,7 +210,7 @@ use the ``package_data`` option, the following configuration will work:
             package_data={"": ["*.txt"], "mypkg1": ["data1.rst"]},
         )
 
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml (**BETA**) [#beta]_
 
    .. code-block:: toml
 
@@ -288,7 +288,7 @@ use the ``exclude_package_data`` option:
             exclude_package_data={"mypkg": [".gitattributes"]},
         )
 
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml (**BETA**) [#beta]_
 
    .. code-block:: toml
 
@@ -365,7 +365,7 @@ the configuration might look like this:
             }
         )
 
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml (**BETA**) [#beta]_
 
    .. code-block:: toml
 
@@ -412,7 +412,7 @@ scanning of namespace packages in the ``src`` directory and the rest is handled
             include_package_data=True,
         )
 
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml (**BETA**) [#beta]_
 
    .. code-block:: toml
 
@@ -539,10 +539,10 @@ run time be included **inside the package**.
 
 ----
 
-.. [#experimental]
-   Support for specifying package metadata and build configuration options via
-   ``pyproject.toml`` is experimental and might change
-   in the future. See :doc:`/userguide/pyproject_config`.
+.. [#beta]
+   Support for adding build configuration options via the ``[tool.setuptools]``
+   in the ``pyproject.toml`` file table is still in **beta** stage.
+   See :doc:`/userguide/pyproject_config`.
 
 .. [#system-dirs] These locations can be discovered with the help of
    third-party libraries such as :pypi:`platformdirs`.
diff --git a/docs/userguide/entry_point.rst b/docs/userguide/entry_point.rst
index b7dd7aa917..bad083f490 100644
--- a/docs/userguide/entry_point.rst
+++ b/docs/userguide/entry_point.rst
@@ -92,7 +92,7 @@ configuration:
             }
         )
 
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml
 
    .. code-block:: toml
 
@@ -162,7 +162,7 @@ Then, we can add a GUI script entry point:
             }
         )
 
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml
 
    .. code-block:: toml
 
@@ -368,7 +368,7 @@ of ``timmins-plugin-fancy``:
             }
         )
 
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml
 
    .. code-block:: toml
 
@@ -441,7 +441,7 @@ The configuration of ``timmins-plugin-fancy`` would then change to:
             }
         )
 
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml
 
    .. code-block:: toml
 
@@ -562,11 +562,6 @@ class or module.
 
 ----
 
-.. [#experimental]
-   Support for specifying package metadata and build configuration options via
-   ``pyproject.toml`` is experimental and might change
-   in the future. See :doc:`/userguide/pyproject_config`.
-
 .. [#use_for_scripts]
    Reference: https://packaging.python.org/en/latest/specifications/entry-points/#use-for-scripts
 
diff --git a/docs/userguide/package_discovery.rst b/docs/userguide/package_discovery.rst
index 4391aa1273..ec282bad86 100644
--- a/docs/userguide/package_discovery.rst
+++ b/docs/userguide/package_discovery.rst
@@ -40,7 +40,7 @@ Normally, you would specify the packages to be included manually in the followin
             packages=['mypkg', 'mypkg.subpkg1', 'mypkg.subpkg2']
         )
 
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml (**BETA**) [#beta]_
 
     .. code-block:: toml
 
@@ -93,7 +93,7 @@ exactly to the directory structure, you also need to configure ``package_dir``:
                 # ...
         )
 
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml (**BETA**) [#beta]_
 
     .. code-block:: toml
 
@@ -128,7 +128,7 @@ the following sections.
 Automatic discovery
 ===================
 
-.. warning:: Automatic discovery is an **experimental** feature and might change
+.. warning:: Automatic discovery is an **beta** feature and might change
    (or be completely removed) in the future.
    See :ref:`custom-discovery` for a stable way of configuring ``setuptools``.
 
@@ -276,7 +276,7 @@ the provided tools for package discovery:
         # or
         from setuptools import find_namespace_packages
 
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml (**BETA**) [#beta]_
 
     .. code-block:: toml
 
@@ -349,7 +349,7 @@ in ``src`` that start with the name ``pkg`` and not ``additional``:
         ``pkg.namespace`` is ignored by ``find_packages()``
         (see ``find_namespace_packages()`` below).
 
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml (**BETA**) [#beta]_
 
     .. code-block:: toml
 
@@ -458,7 +458,7 @@ distribution, then you will need to specify:
     On the other hand, ``find_namespace_packages()`` will scan all
     directories.
 
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml (**BETA**) [#beta]_
 
     .. code-block:: toml
 
@@ -585,10 +585,10 @@ The project layout remains the same and ``setup.cfg`` remains the same.
 ----
 
 
-.. [#experimental]
-   Support for specifying package metadata and build configuration options via
-   ``pyproject.toml`` is experimental and might change
-   in the future. See :doc:`/userguide/pyproject_config`.
+.. [#beta]
+   Support for adding build configuration options via the ``[tool.setuptools]``
+   in the ``pyproject.toml`` file table is still in **beta** stage.
+   See :doc:`/userguide/pyproject_config`.
 .. [#layout1] https://blog.ionelmc.ro/2014/05/25/python-packaging/#the-structure
 .. [#layout2] https://blog.ionelmc.ro/2017/09/25/rehashing-the-src-layout/
 
diff --git a/docs/userguide/pyproject_config.rst b/docs/userguide/pyproject_config.rst
index dcf284d5f3..2b0f9cbc82 100644
--- a/docs/userguide/pyproject_config.rst
+++ b/docs/userguide/pyproject_config.rst
@@ -72,7 +72,7 @@ Setuptools-specific configuration
 .. warning::
    Support for declaring configurations not standardized by :pep:`621`
    (i.e.  the ``[tool.setuptools]`` table),
-   is still **experimental** and might change in future releases.
+   is still in **beta** stage and might change in future releases.
 
 While the standard ``project`` table in the ``pyproject.toml`` file covers most
 of the metadata used during the packaging process, there are still some
@@ -99,7 +99,7 @@ Key                       Value Type (TOML)           Notes
 ``exclude-package-data``  table/inline-table
 ``license-files``         array of glob patterns      **Provisional** - likely to change with :pep:`639`
                                                       (by default: ``['LICEN[CS]E*', 'COPYING*', 'NOTICE*', 'AUTHORS*']``)
-``data-files``            table/inline-table          **Deprecated** - check :doc:`/userguide/datafiles`
+``data-files``            table/inline-table          **Discouraged** - check :doc:`/userguide/datafiles`
 ``script-files``          array                       **Deprecated** - equivalent to the ``script`` keyword in ``setup.py``
                                                       (should be avoided in favour of ``project.scripts``)
 ``provides``              array                       **Ignored by pip**
diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst
index 923b1d4e1b..4e3d73280e 100644
--- a/docs/userguide/quickstart.rst
+++ b/docs/userguide/quickstart.rst
@@ -58,7 +58,7 @@ library will be used to actually do the packaging.
 
 In addition to specifying a build system, you also will need to add
 some package information such as metadata, contents, dependencies, etc.
-This can be done in the same ``pyproject.toml`` [#experimental]_ file,
+This can be done in the same ``pyproject.toml`` [#beta]_ file,
 or in a separated one: ``setup.cfg`` or ``setup.py`` (please note however
 that configuring new projects via ``setup.py`` is discouraged [#setup.py]_).
 
@@ -196,7 +196,7 @@ found, as shown in the example below:
             # ...
         )
 
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml (**BETA**) [#beta]_
 
     .. code-block:: toml
 
@@ -225,7 +225,7 @@ For more details and advanced use, go to :ref:`package_discovery`.
    :ref:`flat-layout` and :ref:`src-layout`) without requiring any
    special configuration. Check out our :ref:`reference docs <package_discovery>`
    for more information, but please keep in mind that this functionality is
-   still considered **experimental** and might change in future releases.
+   still considered **beta** and might change in future releases.
 
 
 Entry points and automatic script creation
@@ -349,7 +349,7 @@ For the simplest use, you can simply use the ``include_package_data`` keyword:
             # ...
         )
 
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml (**BETA**) [#beta]_
 
     .. code-block:: toml
 
@@ -447,9 +447,9 @@ up-to-date references that can help you when it is time to distribute your work.
    <pyproject_config>` and use ``setup.py`` only for the parts not
    supported in those files (e.g. C extensions).
 
-.. [#experimental]
+.. [#beta]
    Support for adding build configuration options via the ``[tool.setuptools]``
-   in the ``pyproject.toml`` file table is still experimental and might change
-   in future releases. See :doc:`/userguide/pyproject_config`.
+   in the ``pyproject.toml`` file table is still in **beta** stage.
+   See :doc:`/userguide/pyproject_config`.
 
 .. _PyPI: https://pypi.org
diff --git a/pytest.ini b/pytest.ini
index 0be8d7e2ef..7c863960b1 100644
--- a/pytest.ini
+++ b/pytest.ini
@@ -59,4 +59,4 @@ filterwarnings=
 	ignore:Distutils was imported before setuptools
 	ignore:Setuptools is replacing distutils
 
-	ignore:Support for configuring .* in .pyproject.toml. is still experimental
+	ignore:Support for .* in .pyproject.toml. is still .beta.
diff --git a/setuptools/config/pyprojecttoml.py b/setuptools/config/pyprojecttoml.py
index ce5ad04d7a..e9532d41b9 100644
--- a/setuptools/config/pyprojecttoml.py
+++ b/setuptools/config/pyprojecttoml.py
@@ -96,11 +96,8 @@ def read_configuration(
 
     if setuptools_table:
         # TODO: Remove the following once the feature stabilizes:
-        msg = (
-            "Support for configuring `[tool.setuptools]` in `pyproject.toml` is still "
-            "experimental and may change in future releases."
-        )
-        warnings.warn(msg, _ExperimentalConfiguration)
+        msg = "Support for `[tool.setuptools]` in `pyproject.toml` is still *beta*."
+        warnings.warn(msg, _BetaConfiguration)
 
     # There is an overall sense in the community that making include_package_data=True
     # the default would be an improvement.
@@ -414,8 +411,8 @@ def __exit__(self, exc_type, exc_value, traceback):
         return super().__exit__(exc_type, exc_value, traceback)
 
 
-class _ExperimentalConfiguration(UserWarning):
-    """Explicitly inform users that `pyproject.toml` configuration is experimental"""
+class _BetaConfiguration(UserWarning):
+    """Explicitly inform users that some `pyproject.toml` configuration is *beta*"""
 
 
 class _InvalidFile(UserWarning):

From 9d487039eaab63eda2283c69653ef1b09ccf702d Mon Sep 17 00:00:00 2001
From: Anderson Bravalheri <andersonbravalheri@gmail.com>
Date: Thu, 16 Jun 2022 21:59:01 +0100
Subject: [PATCH 5/7] docs: Reorder example tabs

---
 docs/userguide/dependency_management.rst | 115 +++++++++++-----------
 docs/userguide/entry_point.rst           |  68 ++++++-------
 docs/userguide/quickstart.rst            | 117 ++++++++++++-----------
 3 files changed, 150 insertions(+), 150 deletions(-)

diff --git a/docs/userguide/dependency_management.rst b/docs/userguide/dependency_management.rst
index f92e22c49f..56fbd0bdd3 100644
--- a/docs/userguide/dependency_management.rst
+++ b/docs/userguide/dependency_management.rst
@@ -53,6 +53,18 @@ be able to run. ``setuptools`` supports automatically downloading and installing
 these dependencies when the package is installed. Although there is more
 finesse to it, let's start with a simple example.
 
+.. tab:: pyproject.toml
+
+    .. code-block:: toml
+
+        [project]
+        # ...
+        dependencies = [
+            "docutils",
+            "BazSpam == 1.1",
+        ]
+        # ...
+
 .. tab:: setup.cfg
 
     .. code-block:: ini
@@ -75,18 +87,6 @@ finesse to it, let's start with a simple example.
             ],
         )
 
-.. tab:: pyproject.toml
-
-    .. code-block:: toml
-
-        [project]
-        # ...
-        dependencies = [
-            "docutils",
-            "BazSpam == 1.1",
-        ]
-        # ...
-
 
 When your project is installed (e.g., using :pypi:`pip`), all of the dependencies not
 already installed will be located (via `PyPI`_), downloaded, built (if necessary),
@@ -104,6 +104,17 @@ specific dependencies. For example, the ``enum`` package was added in Python
 3.4, therefore, package that depends on it can elect to install it only when
 the Python version is older than 3.4. To accomplish this
 
+.. tab:: pyproject.toml
+
+    .. code-block:: toml
+
+        [project]
+        # ...
+        dependencies = [
+            "enum34; python_version<'3.4'",
+        ]
+        # ...
+
 .. tab:: setup.cfg
 
     .. code-block:: ini
@@ -124,6 +135,9 @@ the Python version is older than 3.4. To accomplish this
             ],
         )
 
+Similarly, if you also wish to declare ``pywin32`` with a minimal version of 1.0
+and only install it if the user is using a Windows operating system:
+
 .. tab:: pyproject.toml
 
     .. code-block:: toml
@@ -132,12 +146,10 @@ the Python version is older than 3.4. To accomplish this
         # ...
         dependencies = [
             "enum34; python_version<'3.4'",
+            "pywin32 >= 1.0; platform_system=='Windows'",
         ]
         # ...
 
-Similarly, if you also wish to declare ``pywin32`` with a minimal version of 1.0
-and only install it if the user is using a Windows operating system:
-
 .. tab:: setup.cfg
 
     .. code-block:: ini
@@ -160,18 +172,6 @@ and only install it if the user is using a Windows operating system:
             ],
         )
 
-.. tab:: pyproject.toml
-
-    .. code-block:: toml
-
-        [project]
-        # ...
-        dependencies = [
-            "enum34; python_version<'3.4'",
-            "pywin32 >= 1.0; platform_system=='Windows'",
-        ]
-        # ...
-
 The environmental markers that may be used for testing platform types are
 detailed in :pep:`508`.
 
@@ -190,6 +190,16 @@ set of extra functionalities.
 For example, let's consider a ``Package-A`` that offers
 optional PDF support and requires two other dependencies for it to work:
 
+.. tab:: pyproject.toml
+
+    .. code-block:: toml
+
+        [project]
+        name = "Package-A"
+        # ...
+        [project.optional-dependencies]
+        PDF = ["ReportLab>=1.2", "RXP"]
+
 .. tab:: setup.cfg
 
     .. code-block:: ini
@@ -215,16 +225,6 @@ optional PDF support and requires two other dependencies for it to work:
             },
         )
 
-.. tab:: pyproject.toml
-
-    .. code-block:: toml
-
-        [project]
-        name = "Package-A"
-        # ...
-        [project.optional-dependencies]
-        PDF = ["ReportLab>=1.2", "RXP"]
-
 .. sidebar::
 
    .. tip::
@@ -238,6 +238,17 @@ A use case for this approach is that other package can use this "extra" for thei
 own dependencies. For example, if ``Package-B`` needs ``Package-B`` with PDF support
 installed, it might declare the dependency like this:
 
+.. tab:: pyproject.toml
+
+    .. code-block:: toml
+
+        [project]
+        name = "Package-B"
+        # ...
+        dependencies = [
+            "Package-A[PDF]"
+        ]
+
 .. tab:: setup.cfg
 
     .. code-block:: ini
@@ -261,17 +272,6 @@ installed, it might declare the dependency like this:
             ...,
         )
 
-.. tab:: pyproject.toml
-
-    .. code-block:: toml
-
-        [project]
-        name = "Package-B"
-        # ...
-        dependencies = [
-            "Package-A[PDF]"
-        ]
-
 This will cause ``ReportLab`` to be installed along with ``Package-A``, if ``Package-B`` is
 installed -- even if ``Package-A`` was already installed.  In this way, a project
 can encapsulate groups of optional "downstream dependencies" under a feature
@@ -338,6 +338,15 @@ Python requirement
 In some cases, you might need to specify the minimum required python version.
 This can be configured as shown in the example below.
 
+.. tab:: pyproject.toml
+
+    .. code-block:: toml
+
+        [project]
+        name = "Package-B"
+        requires-python = ">=3.6"
+        # ...
+
 .. tab:: setup.cfg
 
     .. code-block:: ini
@@ -361,14 +370,4 @@ This can be configured as shown in the example below.
         )
 
 
-.. tab:: pyproject.toml
-
-    .. code-block:: toml
-
-        [project]
-        name = "Package-B"
-        requires-python = ">=3.6"
-        # ...
-
-
 .. _PyPI: https://pypi.org
diff --git a/docs/userguide/entry_point.rst b/docs/userguide/entry_point.rst
index bad083f490..eff20cf090 100644
--- a/docs/userguide/entry_point.rst
+++ b/docs/userguide/entry_point.rst
@@ -29,7 +29,7 @@ First consider an example without entry points. Imagine a package
 defined thus::
 
     project_root_directory
-    ├── setup.py        # and/or setup.cfg, pyproject.toml
+    ├── pyproject.toml        # and/or setup.cfg, setup.py
     └── src
         └── timmins
             ├── __init__.py
@@ -69,6 +69,13 @@ In the above example, to create a command ``hello-world`` that invokes
 ``timmins.hello_world``, add a console script entry point to your
 configuration:
 
+.. tab:: pyproject.toml
+
+   .. code-block:: toml
+
+        [project.scripts]
+        hello-world = "timmins:hello_world"
+
 .. tab:: setup.cfg
 
     .. code-block:: ini
@@ -92,13 +99,6 @@ configuration:
             }
         )
 
-.. tab:: pyproject.toml
-
-   .. code-block:: toml
-
-        [project.scripts]
-        hello-world = "timmins:hello_world"
-
 
 After installing the package, a user may invoke that function by simply calling
 ``hello-world`` on the command line:
@@ -139,6 +139,13 @@ with an ``__init__.py`` file containing the following:
 
 Then, we can add a GUI script entry point:
 
+.. tab:: pyproject.toml
+
+   .. code-block:: toml
+
+        [project.gui-scripts]
+        hello-world = "timmins:hello_world"
+
 .. tab:: setup.cfg
 
     .. code-block:: ini
@@ -150,7 +157,7 @@ Then, we can add a GUI script entry point:
 .. tab:: setup.py
 
     .. code-block:: python
-    
+
         from setuptools import setup
 
         setup(
@@ -162,13 +169,6 @@ Then, we can add a GUI script entry point:
             }
         )
 
-.. tab:: pyproject.toml
-
-   .. code-block:: toml
-
-        [project.gui-scripts]
-        hello-world = "timmins:hello_world"
-
 .. note::
    To be able to import ``PySimpleGUI``, you need to add ``pysimplegui`` to your package dependencies.
    See :doc:`/userguide/dependency_management` for more information.
@@ -236,7 +236,7 @@ corresponding to plugins. Say we have a package ``timmins`` with the following
 directory structure::
 
     timmins
-    ├── setup.py        # and/or setup.cfg, pyproject.toml
+    ├── pyproject.toml        # and/or setup.cfg, setup.py
     └── src
         └── timmins
             └── __init__.py
@@ -328,7 +328,7 @@ which implements the entry point ``timmins.display``. Let us name this plugin
 ``timmins-plugin-fancy``, and set it up with the following directory structure::
 
     timmins-plugin-fancy
-    ├── setup.py        # and/or setup.cfg, pyproject.toml
+    ├── pyproject.toml        # and/or setup.cfg, setup.py
     └── src
         └── timmins_plugin_fancy
             └── __init__.py
@@ -345,6 +345,14 @@ This is the ``display()``-like function that we are looking to supply to the
 ``timmins`` package. We can do that by adding the following in the configuration
 of ``timmins-plugin-fancy``:
 
+.. tab:: pyproject.toml
+
+   .. code-block:: toml
+
+        # Note the quotes around timmins.display in order to escape the dot .
+        [project.entry-points."timmins.display"]
+        excl = "timmins_plugin_fancy:excl_display"
+
 .. tab:: setup.cfg
 
    .. code-block:: ini
@@ -368,14 +376,6 @@ of ``timmins-plugin-fancy``:
             }
         )
 
-.. tab:: pyproject.toml
-
-   .. code-block:: toml
-
-        # Note the quotes around timmins.display in order to escape the dot .
-        [project.entry-points."timmins.display"]
-        excl = "timmins_plugin_fancy:excl_display"
-
 Basically, this configuration states that we are a supplying an entry point
 under the group ``timmins.display``. The entry point is named ``excl`` and it
 refers to the function ``excl_display`` defined by the package ``timmins-plugin-fancy``.
@@ -416,6 +416,14 @@ functions, as follows:
 
 The configuration of ``timmins-plugin-fancy`` would then change to:
 
+.. tab:: pyproject.toml
+
+   .. code-block:: toml
+
+        [project.entry-points."timmins.display"]
+        excl = "timmins_plugin_fancy:excl_display"
+        lined = "timmins_plugin_fancy:lined_display"
+
 .. tab:: setup.cfg
 
    .. code-block:: ini
@@ -441,14 +449,6 @@ The configuration of ``timmins-plugin-fancy`` would then change to:
             }
         )
 
-.. tab:: pyproject.toml
-
-   .. code-block:: toml
-
-        [project.entry-points."timmins.display"]
-        excl = "timmins_plugin_fancy:excl_display"
-        lined = "timmins_plugin_fancy:lined_display"
-
 On the ``timmins`` side, we can also use a different strategy of loading entry
 points. For example, we can search for a specific display style:
 
diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst
index 4e3d73280e..5ee1ce7b14 100644
--- a/docs/userguide/quickstart.rst
+++ b/docs/userguide/quickstart.rst
@@ -66,6 +66,20 @@ The following example demonstrates a minimum configuration
 (which assumes the project depends on :pypi:`requests` and
 :pypi:`importlib-metadata` to be able to run):
 
+.. tab:: pyproject.toml
+
+    .. code-block:: toml
+
+       [project]
+       name = "mypackage"
+       version = "0.0.1"
+       dependencies = [
+           "requests",
+           'importlib-metadata; python_version<"3.8"',
+       ]
+
+    See :doc:`/userguide/pyproject_config` for more information.
+
 .. tab:: setup.cfg
 
     .. code-block:: ini
@@ -98,20 +112,6 @@ The following example demonstrates a minimum configuration
 
     See :doc:`/references/keywords` for more information.
 
-.. tab:: pyproject.toml
-
-    .. code-block:: toml
-
-       [project]
-       name = "mypackage"
-       version = "0.0.1"
-       dependencies = [
-           "requests",
-           'importlib-metadata; python_version<"3.8"',
-       ]
-
-    See :doc:`/userguide/pyproject_config` for more information.
-
 Finally, you will need to organize your Python code to make it ready for
 distributing into something that looks like the following
 (optional files marked with ``#``)::
@@ -166,6 +166,21 @@ Therefore, ``setuptools`` provides a convenient way to customize
 which packages should be distributed and in which directory they should be
 found, as shown in the example below:
 
+.. tab:: pyproject.toml (**BETA**) [#beta]_
+
+    .. code-block:: toml
+
+        # ...
+        [tool.setuptools.packages]
+        find = {}  # Scan the project directory with the default parameters
+
+        # OR
+        [tool.setuptools.packages.find]
+        where = ["src"]  # ["."] by default
+        include = ["mypackage*"]  # ["*"] by default
+        exclude = ["mypackage.tests*"]  # empty by default
+        namespaces = false  # true by default
+
 .. tab:: setup.cfg
 
     .. code-block:: ini
@@ -196,21 +211,6 @@ found, as shown in the example below:
             # ...
         )
 
-.. tab:: pyproject.toml (**BETA**) [#beta]_
-
-    .. code-block:: toml
-
-        # ...
-        [tool.setuptools.packages]
-        find = {}  # Scan the project directory with the default parameters
-
-        # OR
-        [tool.setuptools.packages.find]
-        where = ["src"]  # ["."] by default
-        include = ["mypackage*"]  # ["*"] by default
-        exclude = ["mypackage.tests*"]  # empty by default
-        namespaces = false  # true by default
-
 When you pass the above information, alongside other necessary information,
 ``setuptools`` walks through the directory specified in ``where`` (omitted
 here as the package resides in the current directory) and filters the packages
@@ -239,6 +239,14 @@ to type ``python -m pip install``.
 
 The following configuration examples show how to accomplish this:
 
+
+.. tab:: pyproject.toml
+
+    .. code-block:: toml
+
+       [project.scripts]
+       cli-name = "mypkg.mymodule:some_func"
+
 .. tab:: setup.cfg
 
     .. code-block:: ini
@@ -260,13 +268,6 @@ The following configuration examples show how to accomplish this:
             }
         )
 
-.. tab:: pyproject.toml
-
-    .. code-block:: toml
-
-       [project.scripts]
-       cli-name = "mypkg.mymodule:some_func"
-
 When this project is installed, a ``cli-name`` executable will be created.
 ``cli-name`` will invoke the function ``some_func`` in the
 ``mypkg/mymodule.py`` file when called by the user.
@@ -281,6 +282,18 @@ Packages built with ``setuptools`` can specify dependencies to be automatically
 installed when the package itself is installed.
 The example below show how to configure this kind of dependencies:
 
+.. tab:: pyproject.toml
+
+    .. code-block:: toml
+
+        [project]
+        # ...
+        dependencies = [
+            "docutils",
+            "requires <= 0.4",
+        ]
+        # ...
+
 .. tab:: setup.cfg
 
     .. code-block:: ini
@@ -300,18 +313,6 @@ The example below show how to configure this kind of dependencies:
             # ...
         )
 
-.. tab:: pyproject.toml
-
-    .. code-block:: toml
-
-        [project]
-        # ...
-        dependencies = [
-            "docutils",
-            "requires <= 0.4",
-        ]
-        # ...
-
 Each dependency is represented by a string that can optionally contain version requirements
 (e.g. one of the operators <, >, <=, >=, == or !=, followed by a version identifier),
 and/or conditional environment markers, e.g. ``sys_platform == "win32"``
@@ -332,6 +333,16 @@ Including Data Files
 Setuptools offers three ways to specify data files to be included in your packages.
 For the simplest use, you can simply use the ``include_package_data`` keyword:
 
+.. tab:: pyproject.toml (**BETA**) [#beta]_
+
+    .. code-block:: toml
+
+        [tool.setuptools]
+        include-package-data = true
+        # This is already the default behaviour if your are using
+        # pyproject.toml to configure your build.
+        # You can deactivate that with `include-package-data = false`
+
 .. tab:: setup.cfg
 
     .. code-block:: ini
@@ -349,16 +360,6 @@ For the simplest use, you can simply use the ``include_package_data`` keyword:
             # ...
         )
 
-.. tab:: pyproject.toml (**BETA**) [#beta]_
-
-    .. code-block:: toml
-
-        [tool.setuptools]
-        include-package-data = true
-        # This is already the default behaviour if your are using
-        # pyproject.toml to configure your build.
-        # You can deactivate that with `include-package-data = false`
-
 This tells setuptools to install any data files it finds in your packages.
 The data files must be specified via the |MANIFEST.in|_ file
 or automatically added by a :ref:`Revision Control System plugin

From e85063a9cfcb3de9322fe601f418768f927b73e8 Mon Sep 17 00:00:00 2001
From: Anderson Bravalheri <andersonbravalheri+github@gmail.com>
Date: Fri, 17 Jun 2022 09:38:05 +0100
Subject: [PATCH 6/7] Reorder words in footnote to improve the meaning

---
 docs/userguide/datafiles.rst         | 2 +-
 docs/userguide/package_discovery.rst | 2 +-
 docs/userguide/quickstart.rst        | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/userguide/datafiles.rst b/docs/userguide/datafiles.rst
index 8501e95dc9..e6476c5b90 100644
--- a/docs/userguide/datafiles.rst
+++ b/docs/userguide/datafiles.rst
@@ -541,7 +541,7 @@ run time be included **inside the package**.
 
 .. [#beta]
    Support for adding build configuration options via the ``[tool.setuptools]``
-   in the ``pyproject.toml`` file table is still in **beta** stage.
+   table in the ``pyproject.toml`` file is still in **beta** stage.
    See :doc:`/userguide/pyproject_config`.
 
 .. [#system-dirs] These locations can be discovered with the help of
diff --git a/docs/userguide/package_discovery.rst b/docs/userguide/package_discovery.rst
index ec282bad86..5732b6bcf2 100644
--- a/docs/userguide/package_discovery.rst
+++ b/docs/userguide/package_discovery.rst
@@ -587,7 +587,7 @@ The project layout remains the same and ``setup.cfg`` remains the same.
 
 .. [#beta]
    Support for adding build configuration options via the ``[tool.setuptools]``
-   in the ``pyproject.toml`` file table is still in **beta** stage.
+   table in the ``pyproject.toml`` file is still in **beta** stage.
    See :doc:`/userguide/pyproject_config`.
 .. [#layout1] https://blog.ionelmc.ro/2014/05/25/python-packaging/#the-structure
 .. [#layout2] https://blog.ionelmc.ro/2017/09/25/rehashing-the-src-layout/
diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst
index 5ee1ce7b14..6c39c3529c 100644
--- a/docs/userguide/quickstart.rst
+++ b/docs/userguide/quickstart.rst
@@ -450,7 +450,7 @@ up-to-date references that can help you when it is time to distribute your work.
 
 .. [#beta]
    Support for adding build configuration options via the ``[tool.setuptools]``
-   in the ``pyproject.toml`` file table is still in **beta** stage.
+   table in the ``pyproject.toml`` file is still in **beta** stage.
    See :doc:`/userguide/pyproject_config`.
 
 .. _PyPI: https://pypi.org

From b48a0b209085367dfd1e08d134a250566ec0f2f7 Mon Sep 17 00:00:00 2001
From: Anderson Bravalheri <andersonbravalheri+github@gmail.com>
Date: Fri, 17 Jun 2022 09:48:36 +0100
Subject: [PATCH 7/7] Update docs/userguide/datafiles.rst

---
 docs/userguide/datafiles.rst | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/docs/userguide/datafiles.rst b/docs/userguide/datafiles.rst
index e6476c5b90..44ff742529 100644
--- a/docs/userguide/datafiles.rst
+++ b/docs/userguide/datafiles.rst
@@ -541,8 +541,7 @@ run time be included **inside the package**.
 
 .. [#beta]
    Support for adding build configuration options via the ``[tool.setuptools]``
-   table in the ``pyproject.toml`` file is still in **beta** stage.
-   See :doc:`/userguide/pyproject_config`.
+   table in the ``pyproject.toml`` file. See :doc:`/userguide/pyproject_config`.
 
 .. [#system-dirs] These locations can be discovered with the help of
    third-party libraries such as :pypi:`platformdirs`.