From 8f9b212f0171394fe631ae89c25166e2610eecac Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= Date: Wed, 15 Mar 2023 16:00:18 +0100 Subject: docs: Add a note about historical `wheel` use in `requires` Add a note explaining that the `wheel` requirement that used to be historically used in documentation was incorrect. This also explains why it can frequently be found in existing projects, and what problems it causes. I find myself repeatedly explaining it, so I think having a single official source would be better. Incorporates suggestions from Anderson Bravalheri. --- docs/userguide/quickstart.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'docs') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index bf92f6a2..ead8209d 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -56,6 +56,17 @@ containing a ``build-system`` section similar to the example below: This section declares what are your build system dependencies, and which library will be used to actually do the packaging. +.. note:: + + Historically this documentation has unnecessarily listed ``wheel`` + in the ``requires`` list, and many projects still do that. This is + not recommended. The backend automatically adds ``wheel`` dependency + when it is required, and listing it explicitly causes it to be + unnecessarily required for source distribution builds. + You should only include ``wheel`` in `requires` if you need to explicitly + access it during build time (e.g. if your project needs a ``setup.py`` + script that imports ``wheel``). + In addition to specifying a build system, you also will need to add some package information such as metadata, contents, dependencies, etc. This can be done in the same ``pyproject.toml`` [#beta]_ file, -- cgit v1.2.1 From 1ba53bb500958f6549a2d3af0753c48599adadf5 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Thu, 20 Apr 2023 14:17:21 +0100 Subject: Fix sphinx error --- docs/userguide/quickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index ead8209d..3f97e8ef 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -63,7 +63,7 @@ library will be used to actually do the packaging. not recommended. The backend automatically adds ``wheel`` dependency when it is required, and listing it explicitly causes it to be unnecessarily required for source distribution builds. - You should only include ``wheel`` in `requires` if you need to explicitly + You should only include ``wheel`` in ``requires`` if you need to explicitly access it during build time (e.g. if your project needs a ``setup.py`` script that imports ``wheel``). -- cgit v1.2.1