Clarify warnings and notes in documentation about experimental pyproject.toml

3 files changed, 18 insertions, 32 deletions

diff --git a/docs/userguide/dependency_management.rst b/docs/userguide/dependency_management.rst
index a35d7bfc..f92e22c4 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 8558f5d7..dcf284d5 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 9fcf0939..923b1d4e 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