From db174f01c4ac6438b89fea0fccba41a66813cbb6 Mon Sep 17 00:00:00 2001 From: Vladimir Fokow <57260995+VladimirFokow@users.noreply.github.com> Date: Sun, 4 Feb 2024 21:21:59 +0100 Subject: [PATCH 01/11] update the section with the current info - from issues #3214 , #3518 and #3683 --- docs/userguide/quickstart.rst | 24 +++++++++++++++++------- 1 file changed, 17 insertions(+), 7 deletions(-) diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 3a8e2a3ed4..44b7c88f51 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -442,14 +442,24 @@ distribution so others can use it. This functionality is provided by `. -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 ` 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 - using ``setup.cfg`` or ``pyproject.toml``. + +To ease the challenges of transitioning, :doc:`here ` +we provide a quick guide to understanding how ``setup.cfg`` is parsed by +``setuptools``. Alternatively, :doc:`here ` +is the guide for ``pyproject.toml``. + +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``). Chances are, ``setup.cfg`` will +continue to be maintained for a long time. Currently, ``pyproject.toml`` still +has some `limitations ` for certain users. + + .. _packaging-resources: From 9c2554624c81c3e45220563ae949f8bc01a9e8ce Mon Sep 17 00:00:00 2001 From: Vladimir Fokow <57260995+VladimirFokow@users.noreply.github.com> Date: Sun, 4 Feb 2024 21:38:57 +0100 Subject: [PATCH 02/11] fix link IMO this is a better link - this page lists more issues, and actually compares setup.cfg to pyproject.toml in this sense --- docs/userguide/quickstart.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 44b7c88f51..017c03611c 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -457,8 +457,7 @@ 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``). Chances are, ``setup.cfg`` will continue to be maintained for a long time. Currently, ``pyproject.toml`` still -has some `limitations ` for certain users. - +has some `limitations `. .. _packaging-resources: From 52d74ad85fb45cc961079f6b8e300d5b496af409 Mon Sep 17 00:00:00 2001 From: Vladimir Fokow <57260995+VladimirFokow@users.noreply.github.com> Date: Sun, 4 Feb 2024 21:55:24 +0100 Subject: [PATCH 03/11] add a new fragment --- newsfragments/4200.doc.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 newsfragments/4200.doc.rst diff --git a/newsfragments/4200.doc.rst b/newsfragments/4200.doc.rst new file mode 100644 index 0000000000..4b368683cc --- /dev/null +++ b/newsfragments/4200.doc.rst @@ -0,0 +1 @@ +Updated "Quickstart" to describe the current status of ``setup.cfg`` and ``pyproject.toml`` -- by :user:`VladimirFokow` \ No newline at end of file From 8c36b61aa0de7f3f306c0ca2e9af6b620c332efc Mon Sep 17 00:00:00 2001 From: Vladimir Fokow <57260995+VladimirFokow@users.noreply.github.com> Date: Sun, 4 Feb 2024 21:57:40 +0100 Subject: [PATCH 04/11] fix link syntax --- docs/userguide/quickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 017c03611c..bd544e7fe1 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -457,7 +457,7 @@ 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``). Chances are, ``setup.cfg`` will continue to be maintained for a long time. Currently, ``pyproject.toml`` still -has some `limitations `. +has some `limitations `_. .. _packaging-resources: From 66ed3a50a778c799a48a314b9ff7ac12b35c5314 Mon Sep 17 00:00:00 2001 From: Vladimir Fokow <57260995+VladimirFokow@users.noreply.github.com> Date: Sun, 4 Feb 2024 22:38:04 +0100 Subject: [PATCH 05/11] some fixes after seeing the Preview - fix link - make last paragraph a note (for easier readability) - change language to "still has" to "still may have" to be easier to maintain --- docs/userguide/quickstart.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index bd544e7fe1..4b7b5de294 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -450,15 +450,16 @@ declaratively - using ``setup.cfg`` or ``pyproject.toml``. To ease the challenges of transitioning, :doc:`here ` we provide a quick guide to understanding how ``setup.cfg`` is parsed by -``setuptools``. Alternatively, :doc:`here ` -is the guide for ``pyproject.toml``. +``setuptools``. Alternatively, :doc:`here ` is the +guide for ``pyproject.toml``. -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``). Chances are, ``setup.cfg`` will -continue to be maintained for a long time. Currently, ``pyproject.toml`` still -has some `limitations `_. +.. 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``). Chances are, ``setup.cfg`` will + continue to be maintained for a long time. Currently, ``pyproject.toml`` may + still have some `limitations `_. .. _packaging-resources: From c5535f6247650ae596e0d5046b3d73c6179e2c7c Mon Sep 17 00:00:00 2001 From: Vladimir Fokow <57260995+VladimirFokow@users.noreply.github.com> Date: Sun, 4 Feb 2024 22:42:03 +0100 Subject: [PATCH 06/11] finally fix link --- docs/userguide/quickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 4b7b5de294..58e99f94f7 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -450,7 +450,7 @@ declaratively - using ``setup.cfg`` or ``pyproject.toml``. To ease the challenges of transitioning, :doc:`here ` we provide a quick guide to understanding how ``setup.cfg`` is parsed by -``setuptools``. Alternatively, :doc:`here ` is the +``setuptools``. Alternatively, :doc:`here ` is the guide for ``pyproject.toml``. .. note:: From 601fac92b345e49906670eeda91bb48d4bbdab3c Mon Sep 17 00:00:00 2001 From: Vladimir Fokow <57260995+VladimirFokow@users.noreply.github.com> Date: Mon, 5 Feb 2024 11:48:33 +0100 Subject: [PATCH 07/11] reorder: pyproject.toml first, setup.cfg second --- docs/userguide/quickstart.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 58e99f94f7..f8554da797 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -446,12 +446,12 @@ Transitioning from ``setup.py`` to declarative config ----------------------------------------------------- To avoid executing arbitrary scripts and boilerplate code, we are transitioning from defining all your package information by running ``setup()`` to doing this -declaratively - using ``setup.cfg`` or ``pyproject.toml``. +declaratively - using ``pyproject.toml`` (or older ``setup.cfg``). -To ease the challenges of transitioning, :doc:`here ` -we provide a quick guide to understanding how ``setup.cfg`` is parsed by -``setuptools``. Alternatively, :doc:`here ` is the -guide for ``pyproject.toml``. +To ease the challenges of transitioning, we provide a quick +:doc:`guide ` to understanding how ``pyproject.toml`` +is parsed by ``setuptools``. (Alternatively, :doc:`here ` +is the guide for ``setup.cfg``). .. note:: From 81e5ea81aaf2e8c4791297c081741b866ffbf368 Mon Sep 17 00:00:00 2001 From: Vladimir Fokow <57260995+VladimirFokow@users.noreply.github.com> Date: Mon, 5 Feb 2024 12:00:37 +0100 Subject: [PATCH 08/11] remove the last sentence (it wasn't good) --- docs/userguide/quickstart.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index f8554da797..8f62cd2096 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -446,7 +446,7 @@ Transitioning from ``setup.py`` to declarative config ----------------------------------------------------- To avoid executing arbitrary scripts and boilerplate code, we are transitioning from defining all your package information by running ``setup()`` to doing this -declaratively - using ``pyproject.toml`` (or older ``setup.cfg``). +declaratively - by using ``pyproject.toml`` (or older ``setup.cfg``). To ease the challenges of transitioning, we provide a quick :doc:`guide ` to understanding how ``pyproject.toml`` @@ -457,9 +457,8 @@ is the guide for ``setup.cfg``). 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``). Chances are, ``setup.cfg`` will - continue to be maintained for a long time. Currently, ``pyproject.toml`` may - still have some `limitations `_. + (``pyproject.toml`` / ``setup.cfg``). Yet chances are, ``setup.cfg`` will + continue to be maintained for a long time. .. _packaging-resources: From 2bd9897facf4aad3e2c7bb5aaf436fb37efc59c5 Mon Sep 17 00:00:00 2001 From: Vladimir Fokow <57260995+VladimirFokow@users.noreply.github.com> Date: Mon, 5 Feb 2024 12:08:43 +0100 Subject: [PATCH 09/11] add a comma --- docs/userguide/quickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 8f62cd2096..fcc203294a 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -457,7 +457,7 @@ is the guide for ``setup.cfg``). 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 + (``pyproject.toml`` / ``setup.cfg``). Yet, chances are, ``setup.cfg`` will continue to be maintained for a long time. .. _packaging-resources: From fc2bc7393021f3fac4b68b17693f8239a9780591 Mon Sep 17 00:00:00 2001 From: Vladimir Fokow <57260995+VladimirFokow@users.noreply.github.com> Date: Mon, 5 Feb 2024 12:32:34 +0100 Subject: [PATCH 10/11] replace "usually" with "for example" setup.cfg --- docs/userguide/declarative_config.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/userguide/declarative_config.rst b/docs/userguide/declarative_config.rst index c297c4d35f..1d5bf6ae42 100644 --- a/docs/userguide/declarative_config.rst +++ b/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). From 87b86a5a6993cff7394f7d6bb601d39d9c278186 Mon Sep 17 00:00:00 2001 From: Vladimir Fokow <57260995+VladimirFokow@users.noreply.github.com> Date: Mon, 5 Feb 2024 12:46:26 +0100 Subject: [PATCH 11/11] make links easier to click - by placing them farther apart --- docs/userguide/quickstart.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index fcc203294a..fb1564b8c5 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -450,8 +450,8 @@ declaratively - by using ``pyproject.toml`` (or older ``setup.cfg``). To ease the challenges of transitioning, we provide a quick :doc:`guide ` to understanding how ``pyproject.toml`` -is parsed by ``setuptools``. (Alternatively, :doc:`here ` -is the guide for ``setup.cfg``). +is parsed by ``setuptools``. (Alternatively, here is the +:doc:`guide ` for ``setup.cfg``). .. note::