Add clarifications about experimental status for pyproject.toml configuration

changelog.d/3347.change.rst

@@ -0,0 +1,3 @@
+Changed warnings and documentation notes about *experimental* aspect of ``pyproject.toml`` configuration:
+now ``[pyproject]`` is a fully supported configuration interface, but the ``[tool.setuptools]`` table
+and sub-tables are still considered to be in **beta** stage.

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,9 @@ 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]``
+   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`.

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 (**EXPERIMENTAL**) [#experimental]_
-
-    .. 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,20 +135,21 @@ the Python version is older than 3.4. To accomplish this
             ],
         )
 
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+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
 
         [project]
         # ...
         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 (**EXPERIMENTAL**) [#experimental]_
-
-    .. 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 (**EXPERIMENTAL**) [#experimental]_
-
-    .. 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 (**EXPERIMENTAL**) [#experimental]_
-
-    .. 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,25 +370,4 @@ This can be configured as shown in the example below.
         )
 
 
-.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
-
-    .. code-block:: toml
-
-        [project]
-        name = "Package-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`.
-
-
 .. _PyPI: https://pypi.org