[Docs] Quickstart - add pyproject.toml info to the declarative config section (#4204)

Author: abravalheri

docs/userguide/declarative_config.rst

@@ -11,7 +11,7 @@ Configuring setuptools using ``setup.cfg`` files
     build API) is desired, a ``setup.py`` file containing a ``setup()`` function
     call is still required even if your configuration resides in ``setup.cfg``.
 
-``Setuptools`` allows using configuration files (usually :file:`setup.cfg`)
+``Setuptools`` allows using configuration files (for example, :file:`setup.cfg`)
 to define a package’s metadata and other options that are normally supplied
 to the ``setup()`` function (declarative config).
 

docs/userguide/quickstart.rst

@@ -442,14 +442,23 @@ distribution so others can use it. This functionality is provided by
 <PyPUG:tutorials/packaging-projects>`.
 
 
-Transitioning from ``setup.py`` to ``setup.cfg``
-------------------------------------------------
+Transitioning from ``setup.py`` to declarative config
+-----------------------------------------------------
 To avoid executing arbitrary scripts and boilerplate code, we are transitioning
-into a full-fledged ``setup.cfg`` to declare your package information instead
-of running ``setup()``. This inevitably brings challenges due to a different
-syntax. :doc:`Here </userguide/declarative_config>` we provide a quick guide to
-understanding how ``setup.cfg`` is parsed by ``setuptools`` to ease the pain of
-transition.
+from defining all your package information by running ``setup()`` to doing this
+declaratively - by using ``pyproject.toml`` (or older ``setup.cfg``).
+
+To ease the challenges of transitioning, we provide a quick 
+:doc:`guide </userguide/pyproject_config>` to understanding how ``pyproject.toml``
+is parsed by ``setuptools``. (Alternatively, here is the 
+:doc:`guide </userguide/declarative_config>` for ``setup.cfg``).
+
+.. note::
+
+    The approach ``setuptools`` would like to take is to eventually use a single
+    declarative format (``pyproject.toml``) instead of maintaining 2
+    (``pyproject.toml`` / ``setup.cfg``). Yet, chances are, ``setup.cfg`` will
+    continue to be maintained for a long time.
 
 .. _packaging-resources:
 

newsfragments/4200.doc.rst

@@ -0,0 +1 @@
+Updated "Quickstart" to describe the current status of ``setup.cfg`` and ``pyproject.toml`` -- by :user:`VladimirFokow`