Clarify warnings and notes in documentation about experimental pyproj…

…ect.toml

docs/userguide/dependency_management.rst

@@ -69,7 +69,7 @@ finesse to it, let's start with a simple example.
             ],
         )
 
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml
 
     .. code-block:: toml
 
@@ -116,7 +116,7 @@ the Python version is older than 3.4. To accomplish this
             ],
         )
 
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml
 
     .. code-block:: toml
 
@@ -152,7 +152,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
 
@@ -284,7 +284,7 @@ dependencies for it to work:
             },
         )
 
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml
 
     .. code-block:: toml
 
@@ -322,7 +322,7 @@ installed, it might declare the dependency like this:
             ...,
         )
 
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml
 
     .. code-block:: toml
 
@@ -422,22 +422,11 @@ This can be configured as shown in the example below.
         )
 
 
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml
 
     .. code-block:: toml
 
         [project]
         name = "Project-B"
         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`.

docs/userguide/package_discovery.rst

@@ -586,9 +586,9 @@ 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`.
+   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`.
 .. [#layout1] https://blog.ionelmc.ro/2014/05/25/python-packaging/#the-structure
 .. [#layout2] https://blog.ionelmc.ro/2017/09/25/rehashing-the-src-layout/
 

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

docs/userguide/quickstart.rst

@@ -38,9 +38,9 @@ package your project:
 Then, you will need to specify your package information such as metadata,
 contents, dependencies, etc.
 
-Setuptools currently supports configurations from either ``setup.cfg``,
-``setup.py`` or ``pyproject.toml`` [#experimental]_ files, however, configuring new
-projects via ``setup.py`` is discouraged [#setup.py]_.
+Setuptools currently supports configurations from either ``pyproject.toml``,
+``setup.cfg`` or ``setup.py`` files, however, configuring new projects via
+``setup.py`` is discouraged [#setup.py]_.
 
 The following example demonstrates a minimum configuration:
 
@@ -78,7 +78,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
 
@@ -183,8 +183,7 @@ 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 (or even be removed) in
-   future releases.
+   still considered **experimental** and might change in future releases.
 
 
 Entry points and automatic script creation
@@ -217,7 +216,7 @@ The following configuration examples show how to accomplish this:
             }
         )
 
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml
 
     .. code-block:: toml
 
@@ -257,7 +256,7 @@ The example below show how to configure this kind of dependencies:
             # ...
         )
 
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+.. tab:: pyproject.toml
 
     .. code-block:: toml
 
@@ -407,8 +406,6 @@ 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`.