from setuptools import setup

extras = {
    "docs": [
        "mkdocs-include-markdown-plugin==2.8.0",
        "mkdocs==1.0.4",
        "pymdown-extensions",
        "mkdocs-macros-plugin",
    ],
    "test": [
        "jinja2",
        "pytest>=6",
        "pytest-timeout",
        "pytest-xdist",
    ],
    "bin": [
        "click",
        "ghapi",
        "pip-tools",
        "pygithub",
        "pyyaml",
        "requests",
        "rich>=9.6",
        "packaging>=21.0",
    ],
    "mypy": [
        "mypy>=0.901",
        "types-jinja2",
        "types-certifi",
        "types-toml",
        "types-jinja2",
        "types-pyyaml",
        "types-click",
        "types-requests",
    ],
}

extras["dev"] = [
    *extras["mypy"],
    *extras["test"],
    *extras["bin"],
]

extras["all"] = sum(extras.values(), [])

setup(extras_require=extras)

setup.py
from setuptools import setup

extras = {
    "docs": [
        "mkdocs-include-markdown-plugin==2.8.0",
        "mkdocs==1.0.4",
        "jinja2==3.0.3",
        "pymdown-extensions",
        "mkdocs-macros-plugin",
    ],
    "test": [
        "jinja2",
        "pytest>=6",
        "pytest-timeout",
        "pytest-xdist",
    ],
    "bin": [
        "click",
        "ghapi",
        "pip-tools",
        "pygithub",
        "pyyaml",
        "requests",
        "rich>=9.6",
        "packaging>=21.0",
    ],
    "mypy": [
        "mypy>=0.901",
        "types-jinja2",
        "types-certifi",
        "types-toml",
        "types-jinja2",
        "types-pyyaml",
        "types-click",
        "types-requests",
    ],
}

extras["dev"] = [
    *extras["mypy"],
    *extras["test"],
    *extras["bin"],
]

extras["all"] = sum(extras.values(), [])

setup(extras_require=extras)

setup.py
diff --git a/docs/options.md b/docs/options.md
index 45f67873a..c9d7b7425 100644
--- a/docs/options.md
+++ b/docs/options.md
@@ -402,7 +402,7 @@ This option can also be set using the [command-line option](#command-line)
 > Manually set the Python compatibility of your project
 
 By default, cibuildwheel reads your package's Python compatibility from
-`pyproject.toml` following [PEP621](https://www.python.org/dev/peps/pep-0621/)
+`pyproject.toml` following the [project metadata specification](https://packaging.python.org/en/latest/specifications/declaring-project-metadata/)
 or from `setup.cfg`; finally it will try to inspect the AST of `setup.py` for a
 simple keyword assignment in a top level function call. If you need to override
 this behaviour for some reason, you can use this option.
@@ -416,42 +416,29 @@ Default: reads your package's Python compatibility from `pyproject.toml`
 `setup.py` `setup(python_requires="...")`. If not found, cibuildwheel assumes
 the package is compatible with all versions of Python that it can build.
 
-
 !!! note
-    Rather than using this option, it's recommended you set
-    `project.requires-python` in `pyproject.toml` instead:
-    Example `pyproject.toml`:
+    Rather than using this environment variable, it's recommended you set this value
+    statically in a way that your build backend can use it, too. This ensures
+    that your package's metadata is correct when published on PyPI. This
+    cibuildwheel-specific option is provided as an override, and therefore is only
+    available in environment variable form.
+
+      - If you have a `pyproject.toml` containing a `[project]` table, you can
+        specify `requires-python` there.
 
+        ```toml
         [project]
+        ...
         requires-python = ">=3.6"
+        ```
 
-        # Aside - in pyproject.toml you should always specify minimal build
-        # system options, like this:
-
-        [build-system]
-        requires = ["setuptools>=42", "wheel"]
-        build-backend = "setuptools.build_meta"
-
-
-    Currently, setuptools has not yet added support for reading this value from
-    pyproject.toml yet, and so does not copy it to Requires-Python in the wheel
-    metadata. This mechanism is used by pip to scan through older versions of
-    your package until it finds a release compatible with the current version
-    of Python compatible when installing, so it is an important value to set if
-    you plan to drop support for a version of Python in the future.
-
-    If you don't want to list this value twice, you can also use the setuptools
-    specific location in `setup.cfg` and cibuildwheel will detect it from
-    there. Example `setup.cfg`:
-
-        [options]
-        python_requires = ">=3.6"
-
+        Note that not all build backends fully support using a `[project]` table yet;
+        specifically setuptools just added experimental support in version 61.
+        Adding `[project]` to `pyproject.toml` requires all the other supported
+        values to be specified there, or to be listed in `dynamic`.
 
-This option is not available in `pyproject.toml` under
-`tool.cibuildwheel.project-requires-python`, since it should be set with the
-[PEP621](https://www.python.org/dev/peps/pep-0621/) location instead,
-`project.requires-python`.
+      - If you're using setuptools, [you can set this value in `setup.cfg` (preferred) or `setup.py`](https://setuptools.pypa.io/en/latest/userguide/dependency_management.html#python-requirement)
+        and cibuildwheel will read it from there.
 
 #### Examples
 
diff --git a/setup.py b/setup.py
index 621ccf273..96b4d10c9 100644
--- a/setup.py
+++ b/setup.py
@@ -4,6 +4,7 @@
     "docs": [
         "mkdocs-include-markdown-plugin==2.8.0",
         "mkdocs==1.0.4",
+        "jinja2==3.0.3",
         "pymdown-extensions",
         "mkdocs-macros-plugin",
     ],

[Docs] Example may accidentally be encouraging users to write invalid `pyproject.toml` files
### Description

Hi guys, first of all thank you for the amazing project (always good to remember).

While I was working on adding support for PEP 621 to setuptools, I noticed a series of users having problems with invalid `pyproject.toml` files. The common pattern seem to be a almost empty `[project]` table with only a `requires-python` field set, which is invalid according to PEP 621.

It took me some time to find the reason for this behaviour but I think it comes from:
https://cibuildwheel.readthedocs.io/en/stable/options/#requires-python

I suspect that the example and notes about the preferred way of setting the config has been encouraging users that are unaware of PEP 621 to write technically invalid `pyproject.toml` files.

Please note that this issue is not necessarily related to setuptools itself.
The existence of the `[project]` table in the `pyproject.toml` allows (according to the standard) the installer/builder/consumer program to treat the package differently (specially regarding `dynamic`).

I think it would be nice to at least add a note about this so users became aware of the implications of adding a `[project]` table.

### Build log

_No response_

### CI config

_No response_
