From b4751769add5ec32c494c015b302364c372ae703 Mon Sep 17 00:00:00 2001
From: Henry Schreiner <henryschreineriii@gmail.com>
Date: Sun, 11 May 2025 00:15:21 -0400
Subject: [PATCH 01/19] docs: flip TOML and envvars order

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>
---
 docs/options.md | 686 ++++++++++++++++++++++++++----------------------
 1 file changed, 366 insertions(+), 320 deletions(-)

diff --git a/docs/options.md b/docs/options.md
index 3bd90369f..1bad9af21 100644
--- a/docs/options.md
+++ b/docs/options.md
@@ -75,71 +75,73 @@ See the [cibuildwheel 2 documentation](https://cibuildwheel.pypa.io/en/2.x/) for
 
 #### Examples
 
-!!! tab examples "Environment variables"
+!!! tab examples "pyproject.toml"
 
-    ```yaml
+    ```toml
+    [tool.cibuildwheel]
     # Only build on CPython 3.8
-    CIBW_BUILD: cp38-*
+    build = "cp38-*"
 
     # Skip building on CPython 3.8 on the Mac
-    CIBW_SKIP: cp38-macosx_x86_64
+    skip = "cp38-macosx_x86_64"
 
     # Skip building on CPython 3.8 on all platforms
-    CIBW_SKIP: cp38-*
+    skip = "cp38-*"
 
     # Skip CPython 3.8 on Windows
-    CIBW_SKIP: cp38-win*
+    skip = "cp38-win*"
 
     # Skip CPython 3.8 on 32-bit Windows
-    CIBW_SKIP: cp38-win32
+    skip = "cp38-win32"
 
     # Skip CPython 3.8 and CPython 3.9
-    CIBW_SKIP: cp38-* cp39-*
+    skip = ["cp38-*", "cp39-*"]
 
     # Skip Python 3.8 on Linux
-    CIBW_SKIP: cp38-manylinux*
+    skip = "cp38-manylinux*"
 
     # Skip 32-bit builds
-    CIBW_SKIP: "*-win32 *-manylinux_i686"
+    skip = ["*-win32", "*-manylinux_i686"]
 
     # Disable building PyPy wheels on all platforms
-    CIBW_SKIP: pp*
+    skip = "pp*"
     ```
 
-    Separate multiple selectors with a space.
-
-!!! tab examples "pyproject.toml"
+!!! tab examples "Environment variables"
 
-    ```toml
-    [tool.cibuildwheel]
+    ```yaml
     # Only build on CPython 3.8
-    build = "cp38-*"
+    CIBW_BUILD: cp38-*
 
     # Skip building on CPython 3.8 on the Mac
-    skip = "cp38-macosx_x86_64"
+    CIBW_SKIP: cp38-macosx_x86_64
 
     # Skip building on CPython 3.8 on all platforms
-    skip = "cp38-*"
+    CIBW_SKIP: cp38-*
 
     # Skip CPython 3.8 on Windows
-    skip = "cp38-win*"
+    CIBW_SKIP: cp38-win*
 
     # Skip CPython 3.8 on 32-bit Windows
-    skip = "cp38-win32"
+    CIBW_SKIP: cp38-win32
 
     # Skip CPython 3.8 and CPython 3.9
-    skip = ["cp38-*", "cp39-*"]
+    CIBW_SKIP: cp38-* cp39-*
 
     # Skip Python 3.8 on Linux
-    skip = "cp38-manylinux*"
+    CIBW_SKIP: cp38-manylinux*
 
     # Skip 32-bit builds
-    skip = ["*-win32", "*-manylinux_i686"]
+    CIBW_SKIP: "*-win32 *-manylinux_i686"
 
     # Disable building PyPy wheels on all platforms
-    skip = "pp*"
+    CIBW_SKIP: pp*
     ```
 
+    Separate multiple selectors with a space.
+
+
+
     It is generally recommended to set `CIBW_BUILD` as an environment variable, though `skip`
     tends to be useful in a config file; you can statically declare that you don't
     support PyPy, for example.
@@ -218,34 +220,36 @@ This option can also be set using the [command-line option](#command-line)
 
 #### Examples
 
-!!! tab examples "Environment variables"
+!!! tab examples "pyproject.toml"
 
-    ```yaml
+    ```toml
     # Build `universal2` and `arm64` wheels on an Intel runner.
     # Note that the `arm64` wheel and the `arm64` part of the `universal2`
     # wheel cannot be tested in this configuration.
-    CIBW_ARCHS_MACOS: "x86_64 universal2 arm64"
+    [tool.cibuildwheel.macos]
+    archs = ["x86_64", "universal2", "arm64"]
 
     # On an Linux Intel runner with qemu installed, build Intel and ARM wheels
-    CIBW_ARCHS_LINUX: "auto aarch64"
+    [tool.cibuildwheel.linux]
+    archs = ["auto", "aarch64"]
     ```
 
-    Separate multiple archs with a space.
-
-!!! tab examples "pyproject.toml"
+!!! tab examples "Environment variables"
 
-    ```toml
+    ```yaml
     # Build `universal2` and `arm64` wheels on an Intel runner.
     # Note that the `arm64` wheel and the `arm64` part of the `universal2`
     # wheel cannot be tested in this configuration.
-    [tool.cibuildwheel.macos]
-    archs = ["x86_64", "universal2", "arm64"]
+    CIBW_ARCHS_MACOS: "x86_64 universal2 arm64"
 
     # On an Linux Intel runner with qemu installed, build Intel and ARM wheels
-    [tool.cibuildwheel.linux]
-    archs = ["auto", "aarch64"]
+    CIBW_ARCHS_LINUX: "auto aarch64"
     ```
 
+    Separate multiple archs with a space.
+
+
+
     It is generally recommended to use the environment variable or
     command-line option for Linux, as selecting archs often depends
     on your specific runner having qemu installed.
@@ -295,6 +299,18 @@ the package is compatible with all versions of Python that it can build.
 
 #### Examples
 
+!!! tab examples "pyproject.toml"
+
+    ```toml
+    [tool.cibuildwheel]
+    # Enable free-threaded support
+    enable = ["cpython-freethreading"]
+
+    # Skip building free-threaded compatible wheels on Windows
+    enable = ["cpython-freethreading"]
+    skip = "*t-win*"
+    ```
+
 !!! tab examples "Environment variables"
 
     ```yaml
@@ -373,17 +389,7 @@ partial list in environment variables; use `CIBW_SKIP` instead.
     It is generally recommended to use `cpython-freethreading` in a config
     file as you can statically declare that you support free-threaded builds.
 
-!!! tab examples "pyproject.toml"
-
-    ```toml
-    [tool.cibuildwheel]
-    # Enable free-threaded support
-    enable = ["cpython-freethreading"]
 
-    # Skip building free-threaded compatible wheels on Windows
-    enable = ["cpython-freethreading"]
-    skip = "*t-win*"
-    ```
 
     It is generally not recommended to use `cpython-prerelease` in a config file,
     as it's intended for testing pre-releases for a 2-3 month period only.
@@ -404,6 +410,26 @@ This option can also be set using the [command-line option](#command-line)
 
 #### Examples
 
+!!! tab examples "pyproject.toml"
+
+    ```toml
+    [tool.cibuildwheel]
+    # Switch to using build
+    build-frontend = "build"
+
+    # Ensure pip is used even if the default changes in the future
+    build-frontend = "pip"
+
+    # supply an extra argument to 'pip wheel'
+    build-frontend = { name = "pip", args = ["--no-build-isolation"] }
+
+    # Use uv and build
+    build-frontend = "build[uv]"
+
+    # Use uv and build with an argument
+    build-frontend = { name = "build[uv]", args = ["--no-isolation"] }
+    ```
+
 !!! tab examples "Environment variables"
 
     ```yaml
@@ -471,25 +497,7 @@ optional `args` option.
     CIBW_BUILD_FRONTEND: "build[uv]; args: --no-isolation"
     ```
 
-!!! tab examples "pyproject.toml"
-
-    ```toml
-    [tool.cibuildwheel]
-    # Switch to using build
-    build-frontend = "build"
-
-    # Ensure pip is used even if the default changes in the future
-    build-frontend = "pip"
-
-    # supply an extra argument to 'pip wheel'
-    build-frontend = { name = "pip", args = ["--no-build-isolation"] }
-
-    # Use uv and build
-    build-frontend = "build[uv]"
 
-    # Use uv and build with an argument
-    build-frontend = { name = "build[uv]", args = ["--no-isolation"] }
-    ```
 
 ### `CIBW_CONFIG_SETTINGS` {: #config-settings}
 > Specify config-settings for the build backend.
@@ -508,18 +516,20 @@ Platform-specific environment variables also available:<br/>
 
 #### Examples
 
+!!! tab examples "pyproject.toml"
+
+    ```toml
+    [tool.cibuildwheel.config-settings]
+    --build-option = "--use-mypyc"
+    ```
+
 !!! tab examples "Environment variables"
 
     ```yaml
     CIBW_CONFIG_SETTINGS: "--build-option=--use-mypyc"
     ```
 
-!!! tab examples "pyproject.toml"
 
-    ```toml
-    [tool.cibuildwheel.config-settings]
-    --build-option = "--use-mypyc"
-    ```
 
 
 ### `CIBW_ENVIRONMENT` {: #environment}
@@ -538,35 +548,6 @@ Platform-specific environment variables are also available:<br/>
 
 #### Examples
 
-!!! tab examples "Environment variables"
-
-    ```yaml
-    # Set some compiler flags
-    CIBW_ENVIRONMENT: CFLAGS='-g -Wall' CXXFLAGS='-Wall'
-
-    # Append a directory to the PATH variable (this is expanded in the build environment)
-    CIBW_ENVIRONMENT: PATH=$PATH:/usr/local/bin
-
-    # Prepend a directory containing spaces on Windows.
-    CIBW_ENVIRONMENT_WINDOWS: >
-      PATH="C:\\Program Files\\PostgreSQL\\13\\bin;$PATH"
-
-    # Set BUILD_TIME to the output of the `date` command
-    CIBW_ENVIRONMENT: BUILD_TIME="$(date)"
-
-    # Supply options to `pip` to affect how it downloads dependencies
-    CIBW_ENVIRONMENT: PIP_EXTRA_INDEX_URL=https://pypi.myorg.com/simple
-
-    # Any pip command-line options can be set using the PIP_ prefix
-    # https://pip.pypa.io/en/stable/topics/configuration/#environment-variables
-    CIBW_ENVIRONMENT: PIP_GLOBAL_OPTION="build_ext -j4"
-
-    # Set two flags on linux only
-    CIBW_ENVIRONMENT_LINUX: BUILD_TIME="$(date)" SAMPLE_TEXT="sample text"
-    ```
-
-    Separate multiple values with a space.
-
 !!! tab examples "pyproject.toml"
 
     ```toml
@@ -604,6 +585,37 @@ Platform-specific environment variables are also available:<br/>
     SAMPLE_TEXT = "sample text"
     ```
 
+!!! tab examples "Environment variables"
+
+    ```yaml
+    # Set some compiler flags
+    CIBW_ENVIRONMENT: CFLAGS='-g -Wall' CXXFLAGS='-Wall'
+
+    # Append a directory to the PATH variable (this is expanded in the build environment)
+    CIBW_ENVIRONMENT: PATH=$PATH:/usr/local/bin
+
+    # Prepend a directory containing spaces on Windows.
+    CIBW_ENVIRONMENT_WINDOWS: >
+      PATH="C:\\Program Files\\PostgreSQL\\13\\bin;$PATH"
+
+    # Set BUILD_TIME to the output of the `date` command
+    CIBW_ENVIRONMENT: BUILD_TIME="$(date)"
+
+    # Supply options to `pip` to affect how it downloads dependencies
+    CIBW_ENVIRONMENT: PIP_EXTRA_INDEX_URL=https://pypi.myorg.com/simple
+
+    # Any pip command-line options can be set using the PIP_ prefix
+    # https://pip.pypa.io/en/stable/topics/configuration/#environment-variables
+    CIBW_ENVIRONMENT: PIP_GLOBAL_OPTION="build_ext -j4"
+
+    # Set two flags on linux only
+    CIBW_ENVIRONMENT_LINUX: BUILD_TIME="$(date)" SAMPLE_TEXT="sample text"
+    ```
+
+    Separate multiple values with a space.
+
+
+
     In configuration mode, you can use a [TOML][] table instead of a raw string as shown above.
 
 !!! note
@@ -674,6 +686,24 @@ Platform-specific environment variables also available:<br/>
 
 #### Examples
 
+!!! tab examples "pyproject.toml"
+
+    ```toml
+    # Build third party library
+    [tool.cibuildwheel]
+    before-all = "make -C third_party_lib"
+
+    # Install system library
+    [tool.cibuildwheel.linux]
+    before-all = "yum install -y libffi-devel"
+
+    # Run multiple commands using an array
+    before-all = [
+      "yum install bzip2 -y",
+      "make third_party",
+    ]
+    ```
+
 !!! tab examples "Environment variables"
 
     ```yaml
@@ -694,23 +724,7 @@ Platform-specific environment variables also available:<br/>
     ensures that errors are not ignored. [Further reading on multiline YAML
     here.](https://yaml-multiline.info).
 
-!!! tab examples "pyproject.toml"
-
-    ```toml
-    # Build third party library
-    [tool.cibuildwheel]
-    before-all = "make -C third_party_lib"
-
-    # Install system library
-    [tool.cibuildwheel.linux]
-    before-all = "yum install -y libffi-devel"
 
-    # Run multiple commands using an array
-    before-all = [
-      "yum install bzip2 -y",
-      "make third_party",
-    ]
-    ```
 
     In configuration files, you can use a TOML array, and each line will be run sequentially - joined with `&&`.
 
@@ -734,30 +748,14 @@ Platform-specific environment variables are also available:<br/>
 
 #### Examples
 
-!!! tab examples "Environment variables"
+!!! tab examples "pyproject.toml"
 
-    ```yaml
-    # Install something required for the build (you might want to use pyproject.toml instead)
-    CIBW_BEFORE_BUILD: pip install pybind11
+    ```toml
+    [tool.cibuildwheel]
 
-    # Chain commands using &&
-    CIBW_BEFORE_BUILD_LINUX: python scripts/install-deps.py && make clean
-
-    # Run a script that's inside your project
-    CIBW_BEFORE_BUILD: bash scripts/prepare_for_build.sh
-
-    # If cibuildwheel is called with a package_dir argument, it's available as {package}
-    CIBW_BEFORE_BUILD: "{package}/script/prepare_for_build.sh"
-    ```
-
-!!! tab examples "pyproject.toml"
-
-    ```toml
-    [tool.cibuildwheel]
-
-    # Install something required for the build
-    # (you might want to use build-system.requires instead)
-    before-build = "pip install pybind11"
+    # Install something required for the build
+    # (you might want to use build-system.requires instead)
+    before-build = "pip install pybind11"
 
     # Chain commands using && or make an array.
     before-build = "python scripts/install-deps.py && make clean"
@@ -773,6 +771,24 @@ Platform-specific environment variables are also available:<br/>
     before-build = "{package}/script/prepare_for_build.sh"
     ```
 
+!!! tab examples "Environment variables"
+
+    ```yaml
+    # Install something required for the build (you might want to use pyproject.toml instead)
+    CIBW_BEFORE_BUILD: pip install pybind11
+
+    # Chain commands using &&
+    CIBW_BEFORE_BUILD_LINUX: python scripts/install-deps.py && make clean
+
+    # Run a script that's inside your project
+    CIBW_BEFORE_BUILD: bash scripts/prepare_for_build.sh
+
+    # If cibuildwheel is called with a package_dir argument, it's available as {package}
+    CIBW_BEFORE_BUILD: "{package}/script/prepare_for_build.sh"
+    ```
+
+
+
     In configuration mode, you can use a array, and the items will be joined with `&&`. In TOML, using a single-quote string will avoid escapes - useful for
     Windows paths.
 
@@ -820,6 +836,14 @@ Platform-specific environment variables are also available on platforms that use
 
 #### Examples
 
+!!! tab examples "pyproject.toml"
+
+    ```toml
+    [tool.cibuildwheel]
+    # Allow access to the cmake and rustc binaries in the isolated cross-build environment.
+    xbuild-tools = ["cmake", "rustc"]
+    ```
+
 !!! tab examples "Environment variables"
 
     ```yaml
@@ -832,13 +856,7 @@ Platform-specific environment variables are also available on platforms that use
     CIBW_XBUILD_TOOLS:
     ```
 
-!!! tab examples "pyproject.toml"
 
-    ```toml
-    [tool.cibuildwheel]
-    # Allow access to the cmake and rustc binaries in the isolated cross-build environment.
-    xbuild-tools = ["cmake", "rustc"]
-    ```
 
     ```toml
     [tool.cibuildwheel]
@@ -888,36 +906,6 @@ Platform-specific environment variables are also available:<br/>
 
 #### Examples
 
-!!! tab examples "Environment variables"
-
-    ```yaml
-    # Use delvewheel on windows
-    CIBW_BEFORE_BUILD_WINDOWS: "pip install delvewheel"
-    CIBW_REPAIR_WHEEL_COMMAND_WINDOWS: "delvewheel repair -w {dest_dir} {wheel}"
-
-    # Don't repair macOS wheels
-    CIBW_REPAIR_WHEEL_COMMAND_MACOS: ""
-
-    # Pass the `--lib-sdir .` flag to auditwheel on Linux
-    CIBW_REPAIR_WHEEL_COMMAND_LINUX: "auditwheel repair --lib-sdir . -w {dest_dir} {wheel}"
-
-    # Multi-line example - use && to join on all platforms
-    CIBW_REPAIR_WHEEL_COMMAND: >
-      python scripts/repair_wheel.py -w {dest_dir} {wheel} &&
-      python scripts/check_repaired_wheel.py -w {dest_dir} {wheel}
-
-    # Use abi3audit to catch issues with Limited API wheels
-    CIBW_REPAIR_WHEEL_COMMAND_LINUX: >
-      auditwheel repair -w {dest_dir} {wheel} &&
-      pipx run abi3audit --strict --report {wheel}
-    CIBW_REPAIR_WHEEL_COMMAND_MACOS: >
-      delocate-wheel --require-archs {delocate_archs} -w {dest_dir} -v {wheel} &&
-      pipx run abi3audit --strict --report {wheel}
-    CIBW_REPAIR_WHEEL_COMMAND_WINDOWS: >
-      copy {wheel} {dest_dir} &&
-      pipx run abi3audit --strict --report {wheel}
-    ```
-
 !!! tab examples "pyproject.toml"
 
     ```toml
@@ -959,6 +947,38 @@ Platform-specific environment variables are also available:<br/>
     ]
     ```
 
+!!! tab examples "Environment variables"
+
+    ```yaml
+    # Use delvewheel on windows
+    CIBW_BEFORE_BUILD_WINDOWS: "pip install delvewheel"
+    CIBW_REPAIR_WHEEL_COMMAND_WINDOWS: "delvewheel repair -w {dest_dir} {wheel}"
+
+    # Don't repair macOS wheels
+    CIBW_REPAIR_WHEEL_COMMAND_MACOS: ""
+
+    # Pass the `--lib-sdir .` flag to auditwheel on Linux
+    CIBW_REPAIR_WHEEL_COMMAND_LINUX: "auditwheel repair --lib-sdir . -w {dest_dir} {wheel}"
+
+    # Multi-line example - use && to join on all platforms
+    CIBW_REPAIR_WHEEL_COMMAND: >
+      python scripts/repair_wheel.py -w {dest_dir} {wheel} &&
+      python scripts/check_repaired_wheel.py -w {dest_dir} {wheel}
+
+    # Use abi3audit to catch issues with Limited API wheels
+    CIBW_REPAIR_WHEEL_COMMAND_LINUX: >
+      auditwheel repair -w {dest_dir} {wheel} &&
+      pipx run abi3audit --strict --report {wheel}
+    CIBW_REPAIR_WHEEL_COMMAND_MACOS: >
+      delocate-wheel --require-archs {delocate_archs} -w {dest_dir} -v {wheel} &&
+      pipx run abi3audit --strict --report {wheel}
+    CIBW_REPAIR_WHEEL_COMMAND_WINDOWS: >
+      copy {wheel} {dest_dir} &&
+      pipx run abi3audit --strict --report {wheel}
+    ```
+
+
+
     In configuration mode, you can use an inline array, and the items will be joined with `&&`.
 
 
@@ -1023,6 +1043,31 @@ Auditwheel detects the version of the manylinux / musllinux standard in the imag
 #### Examples
 
 
+!!! tab examples "pyproject.toml"
+
+    ```toml
+    [tool.cibuildwheel]
+    # Build using the manylinux2014 image
+    manylinux-x86_64-image = "manylinux2014"
+    manylinux-i686-image = "manylinux2014"
+    manylinux-pypy_x86_64-image = "manylinux2014"
+    manylinux-pypy_i686-image = "manylinux2014"
+
+    # Build using the latest manylinux2010 release
+    manylinux-x86_64-image = "quay.io/pypa/manylinux2010_x86_64:latest"
+    manylinux-i686-image = "quay.io/pypa/manylinux2010_i686:latest"
+    manylinux-pypy_x86_64-image = "quay.io/pypa/manylinux2010_x86_64:latest"
+    manylinux-pypy_i686-image = "quay.io/pypa/manylinux2010_i686:latest"
+
+    # Build using a different image from the docker registry
+    manylinux-x86_64-image = "dockcross/manylinux-x64"
+    manylinux-i686-image = "dockcross/manylinux-x86"
+
+    # Build musllinux wheels using the musllinux_1_1 image
+    musllinux-x86_64-image = "quay.io/pypa/musllinux_1_1_x86_64:latest"
+    musllinux-i686-image = "quay.io/pypa/musllinux_1_1_i686:latest"
+    ```
+
 !!! tab examples "Environment variables"
 
     ```yaml
@@ -1047,30 +1092,7 @@ Auditwheel detects the version of the manylinux / musllinux standard in the imag
     CIBW_MUSLLINUX_I686_IMAGE: quay.io/pypa/musllinux_1_1_i686:latest
     ```
 
-!!! tab examples "pyproject.toml"
-
-    ```toml
-    [tool.cibuildwheel]
-    # Build using the manylinux2014 image
-    manylinux-x86_64-image = "manylinux2014"
-    manylinux-i686-image = "manylinux2014"
-    manylinux-pypy_x86_64-image = "manylinux2014"
-    manylinux-pypy_i686-image = "manylinux2014"
-
-    # Build using the latest manylinux2010 release
-    manylinux-x86_64-image = "quay.io/pypa/manylinux2010_x86_64:latest"
-    manylinux-i686-image = "quay.io/pypa/manylinux2010_i686:latest"
-    manylinux-pypy_x86_64-image = "quay.io/pypa/manylinux2010_x86_64:latest"
-    manylinux-pypy_i686-image = "quay.io/pypa/manylinux2010_i686:latest"
 
-    # Build using a different image from the docker registry
-    manylinux-x86_64-image = "dockcross/manylinux-x64"
-    manylinux-i686-image = "dockcross/manylinux-x86"
-
-    # Build musllinux wheels using the musllinux_1_1 image
-    musllinux-x86_64-image = "quay.io/pypa/musllinux_1_1_x86_64:latest"
-    musllinux-i686-image = "quay.io/pypa/musllinux_1_1_i686:latest"
-    ```
 
     Like any other option, these can be placed in `[tool.cibuildwheel.linux]`
     if you prefer; they have no effect on `macos` and `windows`.
@@ -1110,34 +1132,36 @@ Options can be supplied after the name.
 
 #### Examples
 
-!!! tab examples "Environment variables"
+!!! tab examples "pyproject.toml"
 
-    ```yaml
+    ```toml
+    [tool.cibuildwheel]
     # use podman instead of docker
-    CIBW_CONTAINER_ENGINE: podman
+    container-engine = "podman"
 
     # pass command line options to 'docker create'
-    CIBW_CONTAINER_ENGINE: "docker; create_args: --gpus all"
+    container-engine = { name = "docker", create-args = ["--gpus", "all"]}
 
     # disable the /host mount
-    CIBW_CONTAINER_ENGINE: "docker; disable_host_mount: true"
+    container-engine = { name = "docker", disable-host-mount = true }
     ```
 
-!!! tab examples "pyproject.toml"
+!!! tab examples "Environment variables"
 
-    ```toml
-    [tool.cibuildwheel]
+    ```yaml
     # use podman instead of docker
-    container-engine = "podman"
+    CIBW_CONTAINER_ENGINE: podman
 
     # pass command line options to 'docker create'
-    container-engine = { name = "docker", create-args = ["--gpus", "all"]}
+    CIBW_CONTAINER_ENGINE: "docker; create_args: --gpus all"
 
     # disable the /host mount
-    container-engine = { name = "docker", disable-host-mount = true }
+    CIBW_CONTAINER_ENGINE: "docker; disable_host_mount: true"
     ```
 
 
+
+
 ### `CIBW_DEPENDENCY_VERSIONS` {: #dependency-versions}
 
 > Control the versions of the tools cibuildwheel uses
@@ -1178,49 +1202,51 @@ Platform-specific environment variables are also available:<br/>
 
 #### Examples
 
-!!! tab examples "Environment variables"
+!!! tab examples "pyproject.toml"
 
-    ```yaml
+    ```toml
+    [tool.cibuildwheel]
     # Use tools versions that are bundled with cibuildwheel (this is the default)
-    CIBW_DEPENDENCY_VERSIONS: pinned
+    dependency-versions = "pinned"
 
     # Use the latest versions available on PyPI
-    CIBW_DEPENDENCY_VERSIONS: latest
+    dependency-versions = "latest"
 
     # Use your own pip constraints file
-    CIBW_DEPENDENCY_VERSIONS: ./constraints.txt
+    dependency-versions = { file = "./constraints.txt" }
 
     # Specify requirements inline
-    CIBW_DEPENDENCY_VERSIONS: "packages: auditwheel==6.2.0"
+    dependency-versions = { packages = ["auditwheel==6.2.0"] }
 
+    [tool.cibuildwheel.pyodide]
     # Choose a specific pyodide-build version
-    CIBW_DEPENDENCY_VERSIONS_PYODIDE: "packages: pyodide-build==0.29.1"
-
-    # Use shell-style quoting around spaces package specifiers
-    CIBW_DEPENDENCY_VERSIONS: "packages: 'pip >=16.0.0, !=17'"
+    dependency-versions = { packages = ["pyodide-build==0.29.1"] }
     ```
 
-!!! tab examples "pyproject.toml"
+!!! tab examples "Environment variables"
 
-    ```toml
-    [tool.cibuildwheel]
+    ```yaml
     # Use tools versions that are bundled with cibuildwheel (this is the default)
-    dependency-versions = "pinned"
+    CIBW_DEPENDENCY_VERSIONS: pinned
 
     # Use the latest versions available on PyPI
-    dependency-versions = "latest"
+    CIBW_DEPENDENCY_VERSIONS: latest
 
     # Use your own pip constraints file
-    dependency-versions = { file = "./constraints.txt" }
+    CIBW_DEPENDENCY_VERSIONS: ./constraints.txt
 
     # Specify requirements inline
-    dependency-versions = { packages = ["auditwheel==6.2.0"] }
+    CIBW_DEPENDENCY_VERSIONS: "packages: auditwheel==6.2.0"
 
-    [tool.cibuildwheel.pyodide]
     # Choose a specific pyodide-build version
-    dependency-versions = { packages = ["pyodide-build==0.29.1"] }
+    CIBW_DEPENDENCY_VERSIONS_PYODIDE: "packages: pyodide-build==0.29.1"
+
+    # Use shell-style quoting around spaces package specifiers
+    CIBW_DEPENDENCY_VERSIONS: "packages: 'pip >=16.0.0, !=17'"
     ```
 
+
+
 ### `CIBW_PYODIDE_VERSION` {: #pyodide-version}
 
 > Specify the Pyodide version to use for `pyodide` platform builds
@@ -1297,25 +1323,6 @@ Platform-specific environment variables are also available:<br/>
 
 #### Examples
 
-!!! tab examples "Environment variables"
-
-    ```yaml
-    # Run the package tests using `pytest`
-    CIBW_TEST_COMMAND: pytest ./tests
-
-    # Trigger an install of the package, but run nothing of note
-    CIBW_TEST_COMMAND: "echo Wheel installed"
-
-    # Multi-line example - join with && on all platforms
-    CIBW_TEST_COMMAND: >
-      pytest ./tests &&
-      python ./test.py
-
-    # run tests on ios
-    CIBW_TEST_SOURCES_IOS: tests
-    CIBW_TEST_COMMAND_IOS: python -m pytest ./tests
-    ```
-
 !!! tab examples "pyproject.toml"
 
     ```toml
@@ -1338,6 +1345,27 @@ Platform-specific environment variables are also available:<br/>
     test-command = "python -m pytest ./tests"
     ```
 
+
+!!! tab examples "Environment variables"
+
+    ```yaml
+    # Run the package tests using `pytest`
+    CIBW_TEST_COMMAND: pytest ./tests
+
+    # Trigger an install of the package, but run nothing of note
+    CIBW_TEST_COMMAND: "echo Wheel installed"
+
+    # Multi-line example - join with && on all platforms
+    CIBW_TEST_COMMAND: >
+      pytest ./tests &&
+      python ./test.py
+
+    # run tests on ios
+    CIBW_TEST_SOURCES_IOS: tests
+    CIBW_TEST_COMMAND_IOS: python -m pytest ./tests
+    ```
+
+
     In configuration files, you can use an array, and the items will be joined with `&&`.
 
 ### `CIBW_BEFORE_TEST` {: #before-test}
@@ -1355,26 +1383,6 @@ Platform-specific environment variables are also available:<br/>
 
 #### Examples
 
-!!! tab examples "Environment variables"
-
-    ```yaml
-    # Install test dependencies with overwritten environment variables.
-    CIBW_BEFORE_TEST: CC=gcc CXX=g++ pip install -r requirements.txt
-
-    # Chain commands using &&
-    CIBW_BEFORE_TEST: rm -rf ./data/cache && mkdir -p ./data/cache
-
-    # Install non pip python package
-    CIBW_BEFORE_TEST: >
-      cd some_dir &&
-      ./configure &&
-      make &&
-      make install
-
-    # Install python packages that are required to install test dependencies
-    CIBW_BEFORE_TEST: pip install cmake scikit-build
-    ```
-
 !!! tab examples "pyproject.toml"
 
     ```toml
@@ -1402,6 +1410,28 @@ Platform-specific environment variables are also available:<br/>
     before-test = "pip install cmake scikit-build"
     ```
 
+!!! tab examples "Environment variables"
+
+    ```yaml
+    # Install test dependencies with overwritten environment variables.
+    CIBW_BEFORE_TEST: CC=gcc CXX=g++ pip install -r requirements.txt
+
+    # Chain commands using &&
+    CIBW_BEFORE_TEST: rm -rf ./data/cache && mkdir -p ./data/cache
+
+    # Install non pip python package
+    CIBW_BEFORE_TEST: >
+      cd some_dir &&
+      ./configure &&
+      make &&
+      make install
+
+    # Install python packages that are required to install test dependencies
+    CIBW_BEFORE_TEST: pip install cmake scikit-build
+    ```
+
+
+
     In configuration files, you can use an array, and the items will be joined with `&&`.
 
 
@@ -1423,6 +1453,14 @@ Platform-specific environment variables are also available:<br/>
 
 #### Examples
 
+!!! tab examples "pyproject.toml"
+
+    ```toml
+    # Copy the "tests" folder, plus "data/test-image.png" from the source folder to the test folder.
+    [tool.cibuildwheel]
+    test-sources = ["tests", "data/test-image.png"]
+    ```
+
 !!! tab examples "Environment variables"
 
     ```yaml
@@ -1430,13 +1468,7 @@ Platform-specific environment variables are also available:<br/>
     CIBW_TEST_SOURCES: tests data/test-image.png
     ```
 
-!!! tab examples "pyproject.toml"
 
-    ```toml
-    # Copy the "tests" folder, plus "data/test-image.png" from the source folder to the test folder.
-    [tool.cibuildwheel]
-    test-sources = ["tests", "data/test-image.png"]
-    ```
 
     In configuration files, you can use an array, and the items will be joined with a space.
 
@@ -1451,16 +1483,6 @@ Platform-specific environment variables are also available:<br/>
 
 #### Examples
 
-!!! tab examples "Environment variables"
-
-    ```yaml
-    # Install pytest before running CIBW_TEST_COMMAND
-    CIBW_TEST_REQUIRES: pytest
-
-    # Install specific versions of test dependencies
-    CIBW_TEST_REQUIRES: pytest==8.2.2 packaging==24.1
-    ```
-
 !!! tab examples "pyproject.toml"
 
     ```toml
@@ -1473,6 +1495,18 @@ Platform-specific environment variables are also available:<br/>
     test-requires = ["pytest==8.2.2", "packaging==24.1"]
     ```
 
+!!! tab examples "Environment variables"
+
+    ```yaml
+    # Install pytest before running CIBW_TEST_COMMAND
+    CIBW_TEST_REQUIRES: pytest
+
+    # Install specific versions of test dependencies
+    CIBW_TEST_REQUIRES: pytest==8.2.2 packaging==24.1
+    ```
+
+
+
     In configuration files, you can use an array, and the items will be joined with a space.
 
 
@@ -1491,6 +1525,14 @@ Platform-specific environment variables are also available:<br/>
 
 #### Examples
 
+!!! tab examples "pyproject.toml"
+
+    ```toml
+    [tool.cibuildwheel]
+    # Will cause the wheel to be installed with `pip install <wheel_file>[test,qt]`
+    test-extras = ["test", "qt"]
+    ```
+
 !!! tab examples "Environment variables"
 
     ```yaml
@@ -1500,13 +1542,7 @@ Platform-specific environment variables are also available:<br/>
 
     Separate multiple items with a comma.
 
-!!! tab examples "pyproject.toml"
 
-    ```toml
-    [tool.cibuildwheel]
-    # Will cause the wheel to be installed with `pip install <wheel_file>[test,qt]`
-    test-extras = ["test", "qt"]
-    ```
 
     In configuration files, you can use an inline array, and the items will be joined with a comma.
 
@@ -1525,6 +1561,14 @@ Platform-specific environment variables are also available:<br/>
 
 #### Examples
 
+!!! tab examples "pyproject.toml"
+
+    ```toml
+    [tool.cibuildwheel]
+    # Will cause the wheel to be installed with these groups of dependencies
+    test-groups = ["test", "qt"]
+    ```
+
 !!! tab examples "Environment variables"
 
     ```yaml
@@ -1534,13 +1578,7 @@ Platform-specific environment variables are also available:<br/>
 
     Separate multiple items with a space.
 
-!!! tab examples "pyproject.toml"
 
-    ```toml
-    [tool.cibuildwheel]
-    # Will cause the wheel to be installed with these groups of dependencies
-    test-groups = ["test", "qt"]
-    ```
 
     In configuration files, you can use an inline array, and the items will be joined with a space.
 
@@ -1555,63 +1593,69 @@ This option is not supported in the overrides section in `pyproject.toml`.
 
 #### Examples
 
-!!! tab examples "Environment variables"
+!!! tab examples "pyproject.toml"
 
-    ```yaml
+    ```toml
+    [tool.cibuildwheel]
     # Will avoid testing on emulated architectures
-    CIBW_TEST_SKIP: "*-*linux_{aarch64,ppc64le,s390x,armv7l}"
+    test-skip = "*-*linux_{aarch64,ppc64le,s390x,armv7l}"
 
     # Skip trying to test arm64 builds on Intel Macs
-    CIBW_TEST_SKIP: "*-macosx_arm64 *-macosx_universal2:arm64"
+    test-skip = "*-macosx_arm64 *-macosx_universal2:arm64"
     ```
 
-!!! tab examples "pyproject.toml"
+!!! tab examples "Environment variables"
 
-    ```toml
-    [tool.cibuildwheel]
+    ```yaml
     # Will avoid testing on emulated architectures
-    test-skip = "*-*linux_{aarch64,ppc64le,s390x,armv7l}"
+    CIBW_TEST_SKIP: "*-*linux_{aarch64,ppc64le,s390x,armv7l}"
 
     # Skip trying to test arm64 builds on Intel Macs
-    test-skip = "*-macosx_arm64 *-macosx_universal2:arm64"
+    CIBW_TEST_SKIP: "*-macosx_arm64 *-macosx_universal2:arm64"
     ```
 
-### `CIBW_TEST_ENVIRONMENT` {: #test-environment}
+
+### `test-environment` {: #test-environment toml env-var }
 
 > Set environment variables for the test environment
 
 A space-separated list of environment variables to set in the test environment.
 
-The syntax is the same as for [`CIBW_ENVIRONMENT`](#environment).
+The syntax is the same as for [`environment`](#environment).
 
-cibuildwheel sets the variable [`PYTHONSAFEPATH`](https://docs.python.org/3/using/cmdline.html#envvar-PYTHONSAFEPATH) to avoid picking up in-tree dependencies when running the tests - we want to test the installed wheel, not the in-tree version. However, this can be overridden by setting `PYTHONSAFEPATH` to an empty string.
+cibuildwheel sets the variable
+[`PYTHONSAFEPATH`](https://docs.python.org/3/using/cmdline.html#envvar-PYTHONSAFEPATH)
+to avoid picking up in-tree dependencies when running the tests - we want to
+test the installed wheel, not the in-tree version. However, this can be
+overridden by setting `PYTHONSAFEPATH` to an empty string.
 
 Platform-specific environment variables are also available:<br/>
 `CIBW_TEST_ENVIRONMENT_MACOS` | `CIBW_TEST_ENVIRONMENT_WINDOWS` | `CIBW_TEST_ENVIRONMENT_LINUX` | `CIBW_TEST_ENVIRONMENT_IOS` | `CIBW_TEST_ENVIRONMENT_PYODIDE`
 
 #### Examples
 
-!!! tab examples "Environment variables"
+!!! tab examples "pyproject.toml"
 
-    ```yaml
+    ```toml
+    [tool.cibuildwheel]
     # Set the environment variable MY_ENV_VAR to "my_value" in the test environment
-    CIBW_TEST_ENVIRONMENT: MY_ENV_VAR=my_value
+    test-environment = { MY_ENV_VAR="my_value" }
 
     # Unset PYTHONSAFEPATH in the test environment
-    CIBW_TEST_ENVIRONMENT: PYTHONSAFEPATH=
+    test-environment = { PYTHONSAFEPATH="" }
     ```
 
-!!! tab examples "pyproject.toml"
+!!! tab examples "Environment variables"
 
-    ```toml
-    [tool.cibuildwheel]
+    ```yaml
     # Set the environment variable MY_ENV_VAR to "my_value" in the test environment
-    test-environment = { MY_ENV_VAR="my_value" }
+    CIBW_TEST_ENVIRONMENT: MY_ENV_VAR=my_value
 
     # Unset PYTHONSAFEPATH in the test environment
-    test-environment = { PYTHONSAFEPATH="" }
+    CIBW_TEST_ENVIRONMENT: PYTHONSAFEPATH=
     ```
 
+
 ## Debugging
 
 ### `CIBW_DEBUG_KEEP_CONTAINER`
@@ -1672,6 +1716,14 @@ Platform-specific environment variables are also available:<br/>
 
 #### Examples
 
+!!! tab examples "pyproject.toml"
+
+    ```toml
+    [tool.cibuildwheel]
+    # Ensure that the build backend output is present
+    build-verbosity = 1
+    ```
+
 !!! tab examples "Environment variables"
 
     ```yaml
@@ -1679,13 +1731,7 @@ Platform-specific environment variables are also available:<br/>
     CIBW_BUILD_VERBOSITY: 1
     ```
 
-!!! tab examples "pyproject.toml"
 
-    ```toml
-    [tool.cibuildwheel]
-    # Ensure that the build backend output is present
-    build-verbosity = 1
-    ```
 
 
 ## Command line {: #command-line}

From da1ef97e3ce28a432970f15a2b73a91467c03d3c Mon Sep 17 00:00:00 2001
From: Joe Rickerby <joerick@mac.com>
Date: Fri, 16 May 2025 18:50:44 +0100
Subject: [PATCH 02/19] Add option tag labels to each header

---
 docs/extra.css  |  4 +++
 docs/options.md | 94 ++++++++++++++++++++++++++++++++++++++++++++-----
 2 files changed, 89 insertions(+), 9 deletions(-)

diff --git a/docs/extra.css b/docs/extra.css
index df7103cea..c8f0953b4 100644
--- a/docs/extra.css
+++ b/docs/extra.css
@@ -47,6 +47,10 @@ h1, h2, h3, h4, h5, h6 {
     padding-bottom: 0.2em;
 }
 
+.wy-nav-content {
+  max-width: 900px;
+}
+
 .rst-content blockquote {
     margin-bottom: 14px;
 }
diff --git a/docs/options.md b/docs/options.md
index 1bad9af21..aeaa52cc8 100644
--- a/docs/options.md
+++ b/docs/options.md
@@ -4,7 +4,7 @@
 
 ## Build selection
 
-### `CIBW_PLATFORM` {: #platform}
+### `platform` {: #platform cmd-line env-var }
 
 > Override the auto-detected target platform
 
@@ -40,7 +40,7 @@ This option can also be set using the [command-line option](#command-line) `--pl
     not require `--platform` or `--arch`, and will override any build/skip
     configuration.
 
-### `CIBW_BUILD`, `CIBW_SKIP` {: #build-skip}
+### `build` & `skip` {: #build-skip toml="build, skip" env-var="CIBW_BUILD, CIBW_SKIP" }
 
 > Choose the Python versions to build
 
@@ -167,7 +167,7 @@ See the [cibuildwheel 2 documentation](https://cibuildwheel.pypa.io/en/2.x/) for
 </style>
 
 
-### `CIBW_ARCHS` {: #archs}
+### `archs` {: #archs cmd-line env-var toml }
 > Change the architectures built on your machine by default.
 
 A list of architectures to build.
@@ -1788,8 +1788,48 @@ Some options support placeholders, like `{project}`, `{package}` or `{wheel}`, t
   .options-toc a.option code {
     font-size: 80%;
   }
-  h3 code {
-    font-size: 100%;
+  .rst-content h3 code {
+    font-size: 115%;
+  }
+  .rst-content h3 code.cmd-line, .rst-content h3 code.toml, .rst-content h3 code.env-var {
+    font-size: 80%;
+    float: right;
+    margin-left: 8px;
+    display: inline-flex;
+    flex-direction: column;
+    justify-content: left;
+    padding-left: 10px;
+    padding-right: 10px;
+    line-height: normal;
+  }
+  .rst-content h3 code.cmd-line:before, .rst-content h3 code.toml:before, .rst-content h3 code.env-var:before {
+    content: ' ';
+    font-size: 10px;
+    font-weight: bold;
+    opacity: 0.3;
+    display: inline-block;
+    border-radius: 5px;
+    margin-left: -3px;
+    margin-right: -3px;
+    margin-bottom: -1px;
+  }
+  .rst-content h3 code.cmd-line:before {
+    content: 'command line';
+  }
+  .rst-content h3 code.cmd-line {
+    background: rgba(224, 202, 56, 0.3);
+  }
+  .rst-content h3 code.toml:before {
+    content: 'pyproject.toml';
+  }
+  .rst-content h3 code.toml {
+    background: rgba(41, 128, 185, 0.3);
+  }
+  .rst-content h3 code.env-var:before {
+    content: 'env var';
+  }
+  .rst-content h3 code.env-var {
+    background: rgba(61, 153, 112, 0.3);
   }
 </style>
 
@@ -1800,9 +1840,6 @@ Some options support placeholders, like `{project}`, `{package}` or `{wheel}`, t
     var headers = []
 
     $('.rst-content h3')
-      .filter(function (i, el) {
-        return !!$(el).text().match(/(^([A-Z0-9, _*]| and )+)¶$/);
-      })
       .each(function (i, el) {
         var optionName = $(el).text().replace('¶', '');
         var description = $(el).next('blockquote').text()
@@ -1881,7 +1918,46 @@ Some options support placeholders, like `{project}`, `{package}` or `{wheel}`, t
         markdown += '|\n'
       }
     }
-
     console.log('readme options markdown\n', markdown)
+
+    // add the option tags to each heading
+    $('.rst-content h3')
+      .each(function (i, el) {
+        el.classList.add('option', 'clearfix');
+        var optionName = $(el).text().replace('¶', '');
+
+        // some options are specified as their env var names
+        if (optionName.startsWith('CIBW_')) {
+          optionName = optionName.replace('CIBW_', '');
+          optionName = optionName.replace(/_/g, '-');
+          optionName = optionName.toLowerCase();
+        }
+
+        var cmdLine = el.getAttribute('cmd-line');
+        var envVar = el.getAttribute('env-var');
+        var toml = el.getAttribute('toml');
+
+        // fill default value
+        if (cmdLine == "cmd-line") {
+          cmdLine = '--'+optionName;
+        }
+        if (envVar == "env-var") {
+          envVar = 'CIBW_'+optionName.toUpperCase().replace(/-/g, '_');
+        }
+        if (toml == "toml") {
+          toml = optionName
+        }
+
+        if (envVar) {
+          $(el).append(' <code class="env-var" title="Environment variable">'+envVar+'</code>');
+        }
+        if (toml) {
+          $(el).append(' <code class="toml" title="TOML option key">'+toml+'</code>');
+        }
+        if (cmdLine) {
+          $(el).append(' <code class="cmd-line" title="Command line argument">'+cmdLine+'</code>');
+        }
+      });
   });
+
 </script>

From c670d5ecda5ba59a7b342ea198dcfc84e0e107d9 Mon Sep 17 00:00:00 2001
From: Henry Schreiner <henryschreineriii@gmail.com>
Date: Sun, 18 May 2025 14:52:34 -0400
Subject: [PATCH 03/19] docs: fix and fill out more

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>
---
 docs/options.md | 181 ++++++++++++++++++++++++------------------------
 1 file changed, 90 insertions(+), 91 deletions(-)

diff --git a/docs/options.md b/docs/options.md
index aeaa52cc8..dbe4cee33 100644
--- a/docs/options.md
+++ b/docs/options.md
@@ -255,7 +255,7 @@ This option can also be set using the [command-line option](#command-line)
     on your specific runner having qemu installed.
 
 
-###  `CIBW_PROJECT_REQUIRES_PYTHON` {: #requires-python}
+###  `CIBW_PROJECT_REQUIRES_PYTHON` {: #requires-python env-var}
 > Manually set the Python compatibility of your project
 
 By default, cibuildwheel reads your package's Python compatibility from
@@ -299,25 +299,13 @@ the package is compatible with all versions of Python that it can build.
 
 #### Examples
 
-!!! tab examples "pyproject.toml"
-
-    ```toml
-    [tool.cibuildwheel]
-    # Enable free-threaded support
-    enable = ["cpython-freethreading"]
-
-    # Skip building free-threaded compatible wheels on Windows
-    enable = ["cpython-freethreading"]
-    skip = "*t-win*"
-    ```
-
 !!! tab examples "Environment variables"
 
     ```yaml
     CIBW_PROJECT_REQUIRES_PYTHON: ">=3.8"
     ```
 
-###  `CIBW_ENABLE` {: #enable}
+###  `CIBW_ENABLE` {: #enable toml env-var}
 > Enable building with extra categories of selectors present.
 
 This option lets you opt-in to non-default builds, like pre-releases and
@@ -369,6 +357,19 @@ partial list in environment variables; use `CIBW_SKIP` instead.
 
 #### Examples
 
+!!! tab examples "pyproject.toml"
+
+    ```toml
+    [tool.cibuildwheel]
+    # Enable free-threaded support
+    enable = ["cpython-freethreading"]
+
+    # Skip building free-threaded compatible wheels on Windows
+    enable = ["cpython-freethreading"]
+    skip = "*t-win*"
+    ```
+
+
 !!! tab examples "Environment variables"
 
     ```yaml
@@ -395,7 +396,7 @@ partial list in environment variables; use `CIBW_SKIP` instead.
     as it's intended for testing pre-releases for a 2-3 month period only.
 
 
-### `CIBW_ALLOW_EMPTY` {: #allow-empty}
+### `CIBW_ALLOW_EMPTY` {: #allow-empty cmd-line env-var}
 > Suppress the error code if no wheels match the specified build identifiers
 
 When none of the specified build identifiers match any available versions,
@@ -410,26 +411,6 @@ This option can also be set using the [command-line option](#command-line)
 
 #### Examples
 
-!!! tab examples "pyproject.toml"
-
-    ```toml
-    [tool.cibuildwheel]
-    # Switch to using build
-    build-frontend = "build"
-
-    # Ensure pip is used even if the default changes in the future
-    build-frontend = "pip"
-
-    # supply an extra argument to 'pip wheel'
-    build-frontend = { name = "pip", args = ["--no-build-isolation"] }
-
-    # Use uv and build
-    build-frontend = "build[uv]"
-
-    # Use uv and build with an argument
-    build-frontend = { name = "build[uv]", args = ["--no-isolation"] }
-    ```
-
 !!! tab examples "Environment variables"
 
     ```yaml
@@ -439,7 +420,7 @@ This option can also be set using the [command-line option](#command-line)
 
 ## Build customization
 
-### `CIBW_BUILD_FRONTEND` {: #build-frontend}
+### `build-frontend` {: #build-frontend cmd-line toml env-var}
 > Set the tool to use to build, either "build" (default), "build\[uv\]", or "pip"
 
 Options:
@@ -478,6 +459,26 @@ optional `args` option.
 
 #### Examples
 
+!!! tab examples "pyproject.toml"
+
+    ```toml
+    [tool.cibuildwheel]
+    # Switch to using build
+    build-frontend = "build"
+
+    # Ensure pip is used even if the default changes in the future
+    build-frontend = "pip"
+
+    # supply an extra argument to 'pip wheel'
+    build-frontend = { name = "pip", args = ["--no-build-isolation"] }
+
+    # Use uv and build
+    build-frontend = "build[uv]"
+
+    # Use uv and build with an argument
+    build-frontend = { name = "build[uv]", args = ["--no-isolation"] }
+    ```
+
 !!! tab examples "Environment variables"
 
     ```yaml
@@ -499,7 +500,7 @@ optional `args` option.
 
 
 
-### `CIBW_CONFIG_SETTINGS` {: #config-settings}
+### `config-settings` {: #config-settings env-var toml}
 > Specify config-settings for the build backend.
 
 Specify config settings for the build backend. Each space separated
@@ -532,7 +533,7 @@ Platform-specific environment variables also available:<br/>
 
 
 
-### `CIBW_ENVIRONMENT` {: #environment}
+### `environment` {: #environment env-var toml}
 > Set environment variables
 
 A list of environment variables to set during the build and test phases. Bash syntax should be used, even on Windows.
@@ -614,8 +615,6 @@ Platform-specific environment variables are also available:<br/>
 
     Separate multiple values with a space.
 
-
-
     In configuration mode, you can use a [TOML][] table instead of a raw string as shown above.
 
 !!! note
@@ -624,7 +623,7 @@ Platform-specific environment variables are also available:<br/>
 !!! note
     To do its work, cibuildwheel sets the variables `VIRTUALENV_PIP`, `DIST_EXTRA_CONFIG`, `SETUPTOOLS_EXT_SUFFIX`, `PIP_DISABLE_PIP_VERSION_CHECK`, `PIP_ROOT_USER_ACTION`, and it extends the variables `PATH` and `PIP_CONSTRAINT`. Your assignments to these options might be replaced or extended.
 
-### `CIBW_ENVIRONMENT_PASS_LINUX` {: #environment-pass}
+### `environment-pass` {: #environment-pass env-var="CIBW_ENVIRONMENT_PASS_LINUX" toml}
 > Set environment variables on the host to pass-through to the container.
 
 A list of environment variables to pass into the linux container during each build and test. It has no effect on the other platforms, which can already access all environment variables directly.
@@ -662,7 +661,7 @@ To specify more than one environment variable, separate the variable names by sp
 
     In configuration mode, you can use a [TOML][] list instead of a raw string as shown above.
 
-### `CIBW_BEFORE_ALL` {: #before-all}
+### `before-all` {: #before-all env-var toml}
 > Execute a shell command on the build system before any wheels are built.
 
 Shell command that runs before any builds are run, to build or install parts that do not depend on the specific version of Python.
@@ -732,7 +731,7 @@ Note that manylinux_2_31 builds occur inside a debian derivative docker containe
 manylinux2014 builds occur inside a CentOS one. So for `manylinux_2_31` the `CIBW_BEFORE_ALL_LINUX` command
 must use `apt-get -y` instead.
 
-### `CIBW_BEFORE_BUILD` {: #before-build}
+### `before-build` {: #before-build env-var toml}
 > Execute a shell command preparing each wheel's build
 
 A shell command to run before building the wheel. This option allows you to run a command in **each** Python environment before the `pip wheel` command. This is useful if you need to set up some dependency so it's available during the build.
@@ -818,7 +817,7 @@ Platform-specific environment variables are also available:<br/>
     [PEP 517]: https://www.python.org/dev/peps/pep-0517/
     [PEP 518]: https://www.python.org/dev/peps/pep-0517/
 
-### `CIBW_XBUILD_TOOLS` {: #xbuild-tools}
+### `xbuild-tools` {: #xbuild-tools env-var toml}
 > Binaries on the path that should be included in an isolated cross-build environment.
 
 When building in a cross-platform environment, it is sometimes necessary to isolate the ``PATH`` so that binaries from the build machine don't accidentally get linked into the cross-platform binary. However, this isolation process will also hide tools that might be required to build your wheel.
@@ -864,7 +863,7 @@ Platform-specific environment variables are also available on platforms that use
     xbuild-tools = []
     ```
 
-### `CIBW_REPAIR_WHEEL_COMMAND` {: #repair-wheel-command}
+### `repair-wheel-command` {: #repair-wheel-command env-var toml}
 > Execute a shell command to repair each built wheel
 
 Default:
@@ -984,40 +983,40 @@ Platform-specific environment variables are also available:<br/>
 
 <div class="link-target" id="manylinux-image"></div>
 
-### `CIBW_MANYLINUX_*_IMAGE`, `CIBW_MUSLLINUX_*_IMAGE` {: #linux-image}
+### `manylinux-*-image`, `musllinux-*-image` {: #linux-image env-var toml}
 
 > Specify manylinux / musllinux container images
 
 The available options are:
 
-| Option                            | Default                                                         |
-|-----------------------------------|-----------------------------------------------------------------|
-| CIBW_MANYLINUX_X86_64_IMAGE       | [`manylinux_2_28`](https://quay.io/pypa/manylinux_2_28_x86_64)  |
-| CIBW_MANYLINUX_I686_IMAGE         | [`manylinux2014`](https://quay.io/pypa/manylinux2014_i686)      |
-| CIBW_MANYLINUX_PYPY_X86_64_IMAGE  | [`manylinux_2_28`](https://quay.io/pypa/manylinux_2_28_x86_64)  |
-| CIBW_MANYLINUX_AARCH64_IMAGE      | [`manylinux_2_28`](https://quay.io/pypa/manylinux_2_28_aarch64) |
-| CIBW_MANYLINUX_PPC64LE_IMAGE      | [`manylinux_2_28`](https://quay.io/pypa/manylinux_2_28_ppc64le) |
-| CIBW_MANYLINUX_S390X_IMAGE        | [`manylinux_2_28`](https://quay.io/pypa/manylinux_2_28_s390x)   |
-| CIBW_MANYLINUX_ARMV7L_IMAGE       | [`manylinux_2_31`](https://quay.io/pypa/manylinux_2_31_armv7l)  |
-| CIBW_MANYLINUX_RISCV64_IMAGE      | No default                                                      |
-| CIBW_MANYLINUX_PYPY_AARCH64_IMAGE | [`manylinux_2_28`](https://quay.io/pypa/manylinux_2_28_aarch64) |
-| CIBW_MANYLINUX_PYPY_I686_IMAGE    | [`manylinux2014`](https://quay.io/pypa/manylinux2014_i686)      |
-| CIBW_MUSLLINUX_X86_64_IMAGE       | [`musllinux_1_2`](https://quay.io/pypa/musllinux_1_2_x86_64)    |
-| CIBW_MUSLLINUX_I686_IMAGE         | [`musllinux_1_2`](https://quay.io/pypa/musllinux_1_2_i686)      |
-| CIBW_MUSLLINUX_AARCH64_IMAGE      | [`musllinux_1_2`](https://quay.io/pypa/musllinux_1_2_aarch64)   |
-| CIBW_MUSLLINUX_PPC64LE_IMAGE      | [`musllinux_1_2`](https://quay.io/pypa/musllinux_1_2_ppc64le)   |
-| CIBW_MUSLLINUX_S390X_IMAGE        | [`musllinux_1_2`](https://quay.io/pypa/musllinux_1_2_s390x)     |
-| CIBW_MUSLLINUX_ARMV7L_IMAGE       | [`musllinux_1_2`](https://quay.io/pypa/musllinux_1_2_armv7l)    |
-| CIBW_MUSLLINUX_RISCV64_IMAGE      | No default                                                      |
+| Option                         | Default                                                         |
+|--------------------------------|-----------------------------------------------------------------|
+| `manylinux-x86-64-image`       | [`manylinux-2-28`](https://quay.io/pypa/manylinux-2-28-x86-64)  |
+| `manylinux-i686-image`         | [`manylinux2014`](https://quay.io/pypa/manylinux2014-i686)      |
+| `manylinux-pypy-x86-64-image`  | [`manylinux-2-28`](https://quay.io/pypa/manylinux-2-28-x86-64)  |
+| `manylinux-aarch64-image`      | [`manylinux-2-28`](https://quay.io/pypa/manylinux-2-28-aarch64) |
+| `manylinux-ppc64le-image`      | [`manylinux-2-28`](https://quay.io/pypa/manylinux-2-28-ppc64le) |
+| `manylinux-s390x-image`        | [`manylinux-2-28`](https://quay.io/pypa/manylinux-2-28-s390x)   |
+| `manylinux-armv7l-image`       | [`manylinux-2-31`](https://quay.io/pypa/manylinux-2-31-armv7l)  |
+| `manylinux-riscv64-image`      | No default                                                      |
+| `manylinux-pypy-aarch64-image` | [`manylinux-2-28`](https://quay.io/pypa/manylinux-2-28-aarch64) |
+| `manylinux-pypy-i686-image`    | [`manylinux2014`](https://quay.io/pypa/manylinux2014-i686)      |
+| `musllinux-x86-64-image`       | [`musllinux-1-2`](https://quay.io/pypa/musllinux-1-2-x86-64)    |
+| `musllinux-i686-image`         | [`musllinux-1-2`](https://quay.io/pypa/musllinux-1-2-i686)      |
+| `musllinux-aarch64-image`      | [`musllinux-1-2`](https://quay.io/pypa/musllinux-1-2-aarch64)   |
+| `musllinux-ppc64le-image`      | [`musllinux-1-2`](https://quay.io/pypa/musllinux-1-2-ppc64le)   |
+| `musllinux-s390x-image`        | [`musllinux-1-2`](https://quay.io/pypa/musllinux-1-2-s390x)     |
+| `musllinux-armv7l-image`       | [`musllinux-1-2`](https://quay.io/pypa/musllinux-1-2-armv7l)    |
+| `musllinux-riscv64-image`      | No default                                                      |
 
 Set the Docker image to be used for building [manylinux / musllinux](https://github.com/pypa/manylinux) wheels.
 
-For `CIBW_MANYLINUX_*_IMAGE`, except `CIBW_MANYLINUX_ARMV7L_IMAGE`, the value of this option can either be set to `manylinux2014`, `manylinux_2_28` or `manylinux_2_34` to use a pinned version of the [official manylinux images](https://github.com/pypa/manylinux). Alternatively, set these options to any other valid Docker image name.
+For `manylinux-*-image`, except `manylinux-armv7l-image`, the value of this option can either be set to `manylinux2014`, `manylinux_2_28` or `manylinux_2_34` to use a pinned version of the [official manylinux images](https://github.com/pypa/manylinux). Alternatively, set these options to any other valid Docker image name.
 `manylinux_2_28` and `manylinux_2_34` are not supported for `i686` architecture.
 
-For `CIBW_MANYLINUX_ARMV7L_IMAGE`, the value of this option can either be set to `manylinux_2_31` or a custom image. Support is experimental for now. The `manylinux_2_31` value is only available for `armv7`.
+For `manylinux-armv7l-image`, the value of this option can either be set to `manylinux_2_31` or a custom image. Support is experimental for now. The `manylinux_2_31` value is only available for `armv7`.
 
-For `CIBW_MUSLLINUX_*_IMAGE`, the value of this option can either be set to `musllinux_1_2` or a custom image.
+For `musllinux-*-image`, the value of this option can either be set to `musllinux_1_2` or a custom image.
 
 If this option is blank, it will fall though to the next available definition (environment variable -> pyproject.toml -> default).
 
@@ -1098,7 +1097,7 @@ Auditwheel detects the version of the manylinux / musllinux standard in the imag
     if you prefer; they have no effect on `macos` and `windows`.
 
 
-### `CIBW_CONTAINER_ENGINE` {: #container-engine}
+### `container-engine` {: #container-engine env-var toml}
 > Specify the container engine to use when building Linux wheels
 
 Options:
@@ -1162,7 +1161,7 @@ Options can be supplied after the name.
 
 
 
-### `CIBW_DEPENDENCY_VERSIONS` {: #dependency-versions}
+### `dependency-versions` {: #dependency-versions env-var toml}
 
 > Control the versions of the tools cibuildwheel uses
 
@@ -1170,7 +1169,7 @@ Options: `pinned` `latest` `packages: SPECIFIER...` `<your constraints file>`
 
 Default: `pinned`
 
-If `CIBW_DEPENDENCY_VERSIONS` is `pinned`, cibuildwheel uses versions of tools
+If `dependency-versions` is `pinned`, cibuildwheel uses versions of tools
 like `pip`, `setuptools`, `virtualenv` that were pinned with that release of
 cibuildwheel. This represents a known-good set of dependencies, and is
 recommended for build repeatability.
@@ -1187,7 +1186,7 @@ specifiers inline with the `packages: SPECIFIER...` syntax.
 !!! note
     If you need different dependencies for each python version, provide them
     in the same folder with a `-pythonXY` suffix. e.g. if your
-    `CIBW_DEPENDENCY_VERSIONS=./constraints.txt`, cibuildwheel will use
+    `dependency-versions="./constraints.txt"`, cibuildwheel will use
     `./constraints-python38.txt` on Python 3.8, or fallback to
     `./constraints.txt` if that's not found.
 
@@ -1197,7 +1196,7 @@ Platform-specific environment variables are also available:<br/>
 !!! note
     This option does not affect the tools used on the Linux build - those versions
     are bundled with the manylinux/musllinux image that cibuildwheel uses. To change
-    dependency versions on Linux, use the [CIBW_MANYLINUX_* / CIBW_MUSLLINUX_*](#linux-image)
+    dependency versions on Linux, use the [`manylinux-*` / `musllinux-*`](#linux-image)
     options.
 
 #### Examples
@@ -1289,7 +1288,7 @@ The available Pyodide versions are determined by the version of `pyodide-build`
 
 ## Testing
 
-### `CIBW_TEST_COMMAND` {: #test-command}
+### `test-command` {: #test-command env-var toml}
 > The command to test each built wheel
 
 Shell command to run tests after the build. The wheel will be installed
@@ -1297,7 +1296,7 @@ automatically and available for import from the tests. If this variable is not
 set, your wheel will not be installed after building.
 
 By default, tests are executed from your project directory. When specifying
-`CIBW_TEST_COMMAND`, you can optionally use the placeholders `{package}` and
+`test-command`, you can optionally use the placeholders `{package}` and
 `{project}` to pass in the location of your test code:
 
 - `{package}` is the path to the package being built - the `package_dir`
@@ -1310,13 +1309,15 @@ Using `{package}` or `{project}` used to be required, but since cibuildwheel
 use relative paths in your test command, and they will be relative to the
 project root.
 
-Alternatively, you can use the [`CIBW_TEST_SOURCES`](#test-sources) setting to
+Alternatively, you can use the [`test_sources`](#test-sources) setting to
 create a temporary folder populated with a specific subset of project files to
 run your test suite.
 
 On all platforms other than iOS, the command is run in a shell, so you can write things like `cmd1 && cmd2`.
 
-On iOS, the value of the `CIBW_TEST_COMMAND` setting must follow the format `python -m MODULE [ARGS...]` - where MODULE is a Python module name, followed by arguments that will be assigned to `sys.argv`. Other commands cannot be used.
+On iOS, the value of the `test-command` setting must follow the format `python
+-m MODULE [ARGS...]` - where MODULE is a Python module name, followed by
+arguments that will be assigned to `sys.argv`. Other commands cannot be used.
 
 Platform-specific environment variables are also available:<br/>
 `CIBW_TEST_COMMAND_MACOS` | `CIBW_TEST_COMMAND_WINDOWS` | `CIBW_TEST_COMMAND_LINUX` | `CIBW_TEST_COMMAND_IOS` | `CIBW_TEST_COMMAND_PYODIDE`
@@ -1368,7 +1369,7 @@ Platform-specific environment variables are also available:<br/>
 
     In configuration files, you can use an array, and the items will be joined with `&&`.
 
-### `CIBW_BEFORE_TEST` {: #before-test}
+### `before-test` {: #before-test env-var toml}
 > Execute a shell command before testing each wheel
 
 A shell command to run in **each** test virtual environment, before your wheel is installed and tested. This is useful if you need to install a non-pip package, invoke pip with different environment variables,
@@ -1435,7 +1436,7 @@ Platform-specific environment variables are also available:<br/>
     In configuration files, you can use an array, and the items will be joined with `&&`.
 
 
-### `CIBW_TEST_SOURCES` {: #test-sources}
+### `test-sources` {: #test-sources env-var toml}
 > Files and folders from the source tree that are copied into an isolated tree before running the tests
 
 A space-separated list of files and folders, relative to the root of the
@@ -1443,7 +1444,7 @@ project, required for running the tests. If specified, these files and folders
 will be copied into a temporary folder, and that temporary folder will be used
 as the working directory for running the test suite.
 
-The use of `CIBW_TEST_SOURCES` is *required* for iOS builds. This is because the
+The use of `test-sources` is *required* for iOS builds. This is because the
 simulator does not have access to the project directory, as it is not stored on
 the simulator device. On iOS, the files will be copied into the test application,
 rather than a temporary folder.
@@ -1473,7 +1474,7 @@ Platform-specific environment variables are also available:<br/>
     In configuration files, you can use an array, and the items will be joined with a space.
 
 
-### `CIBW_TEST_REQUIRES` {: #test-requires}
+### `test_requires` {: #test-requires env-var toml}
 > Install Python dependencies before running the tests
 
 Space-separated list of dependencies required for running the tests.
@@ -1505,19 +1506,17 @@ Platform-specific environment variables are also available:<br/>
     CIBW_TEST_REQUIRES: pytest==8.2.2 packaging==24.1
     ```
 
-
-
     In configuration files, you can use an array, and the items will be joined with a space.
 
 
-### `CIBW_TEST_EXTRAS` {: #test-extras}
+### `test-extras` {: #test-extras env-var toml}
 > Install your wheel for testing using `extras_require`
 
 List of
 [extras_require](https://setuptools.pypa.io/en/latest/userguide/dependency_management.html#declaring-required-dependency)
 options that should be included when installing the wheel prior to running the
 tests. This can be used to avoid having to redefine test dependencies in
-`CIBW_TEST_REQUIRES` if they are already defined in `pyproject.toml`,
+`test-requires` if they are already defined in `pyproject.toml`,
 `setup.cfg` or `setup.py`.
 
 Platform-specific environment variables are also available:<br/>
@@ -1547,14 +1546,14 @@ Platform-specific environment variables are also available:<br/>
     In configuration files, you can use an inline array, and the items will be joined with a comma.
 
 
-### `CIBW_TEST_GROUPS` {: #test-groups}
+### `test-groups` {: #test-groups env-var toml}
 > Specify test dependencies from your project's `dependency-groups`
 
 List of
 [dependency-groups](https://peps.python.org/pep-0735)
 that should be included when installing the wheel prior to running the
 tests. This can be used to avoid having to redefine test dependencies in
-`CIBW_TEST_REQUIRES` if they are already defined in `pyproject.toml`.
+`test-requires` if they are already defined in `pyproject.toml`.
 
 Platform-specific environment variables are also available:<br/>
 `CIBW_TEST_GROUPS_MACOS` | `CIBW_TEST_GROUPS_WINDOWS` | `CIBW_TEST_GROUPS_LINUX` | `CIBW_TEST_GROUPS_PYODIDE`
@@ -1582,7 +1581,7 @@ Platform-specific environment variables are also available:<br/>
 
     In configuration files, you can use an inline array, and the items will be joined with a space.
 
-### `CIBW_TEST_SKIP` {: #test-skip}
+### `test-skip` {: #test-skip env-var toml}
 > Skip running tests on some builds
 
 This will skip testing on any identifiers that match the given skip patterns (see [`CIBW_SKIP`](#build-skip)). This can be used to mask out tests for wheels that have missing dependencies upstream that are slow or hard to build, or to skip slow tests on emulated architectures.
@@ -1658,7 +1657,7 @@ Platform-specific environment variables are also available:<br/>
 
 ## Debugging
 
-### `CIBW_DEBUG_KEEP_CONTAINER`
+### `CIBW_DEBUG_KEEP_CONTAINER` {: #debug-keep-container env-var}
 
 Enable this flag to keep the container around for inspection after a build. This
 option is provided for debugging purposes only.
@@ -1674,7 +1673,7 @@ Default: Off (0).
 export CIBW_DEBUG_KEEP_CONTAINER=TRUE
 ```
 
-### `CIBW_DEBUG_TRACEBACK`
+### `CIBW_DEBUG_TRACEBACK` {: #debug-traceback cmd-line env-var}
 > Print full traceback when errors occur.
 
 Print a full traceback for the cibuildwheel process when errors occur. This
@@ -1688,7 +1687,7 @@ This option can also be set using the [command-line option](#command-line) `--de
 export CIBW_DEBUG_TRACEBACK=TRUE
 ```
 
-### `CIBW_BUILD_VERBOSITY` {: #build-verbosity}
+### `build-verbosity` {: #build-verbosity env-var toml}
 > Increase/decrease the output of the build
 
 This setting controls `-v`/`-q` flags to the build frontend. Since there is

From 0e70ab90770ffe23ec1c9c71fcef46a8e82c50ee Mon Sep 17 00:00:00 2001
From: Henry Schreiner <henryschreineriii@gmail.com>
Date: Sun, 18 May 2025 22:30:50 -0400
Subject: [PATCH 04/19] docs: fix more issues, normalize a bit

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>
---
 docs/options.md | 131 +++++++++++++++++++++---------------------------
 1 file changed, 56 insertions(+), 75 deletions(-)

diff --git a/docs/options.md b/docs/options.md
index dbe4cee33..8623cb15c 100644
--- a/docs/options.md
+++ b/docs/options.md
@@ -352,7 +352,9 @@ builds.
 
 Unlike all other cibuildwheel options, the environment variable setting will
 only add to the TOML config; you can't remove an enable by setting an empty or
-partial list in environment variables; use `CIBW_SKIP` instead.
+partial list in environment variables; use `CIBW_SKIP` instead. This way, if
+you apply `cpython-prerelease` during the beta period using `CIBW_ENABLE`
+without disabling your other enables.
 
 
 #### Examples
@@ -367,6 +369,9 @@ partial list in environment variables; use `CIBW_SKIP` instead.
     # Skip building free-threaded compatible wheels on Windows
     enable = ["cpython-freethreading"]
     skip = "*t-win*"
+
+    # Include all PyPy versions
+    enable = ["pypy", "pypy-eol"]
     ```
 
 
@@ -385,15 +390,11 @@ partial list in environment variables; use `CIBW_SKIP` instead.
     # Skip building free-threaded compatible wheels on Windows
     CIBW_ENABLE: cpython-freethreading
     CIBW_SKIP: *t-win*
-    ```
-
-    It is generally recommended to use `cpython-freethreading` in a config
-    file as you can statically declare that you support free-threaded builds.
-
 
+    # Include all PyPy versions
+    CIBW_ENABLE = pypy pypy-eol
+    ```
 
-    It is generally not recommended to use `cpython-prerelease` in a config file,
-    as it's intended for testing pre-releases for a 2-3 month period only.
 
 
 ### `CIBW_ALLOW_EMPTY` {: #allow-empty cmd-line env-var}
@@ -586,6 +587,8 @@ Platform-specific environment variables are also available:<br/>
     SAMPLE_TEXT = "sample text"
     ```
 
+    In configuration files, you can use a [TOML][] table instead of a raw string as shown above.
+
 !!! tab examples "Environment variables"
 
     ```yaml
@@ -615,8 +618,6 @@ Platform-specific environment variables are also available:<br/>
 
     Separate multiple values with a space.
 
-    In configuration mode, you can use a [TOML][] table instead of a raw string as shown above.
-
 !!! note
     cibuildwheel always defines the environment variable `CIBUILDWHEEL=1`. This can be useful for [building wheels with optional extensions](faq.md#optional-extensions).
 
@@ -635,31 +636,31 @@ To specify more than one environment variable, separate the variable names by sp
 
 #### Examples
 
-!!! tab examples "Environment passthrough"
+!!! tab examples "pyproject.toml"
+
+    ```toml
+    [tool.cibuildwheel.linux]
 
-    ```yaml
     # Export a variable
-    CIBW_ENVIRONMENT_PASS_LINUX: CFLAGS
+    environment-pass = ["CFLAGS"]
 
     # Set two flags variables
-    CIBW_ENVIRONMENT_PASS_LINUX: BUILD_TIME SAMPLE_TEXT
+    environment-pass = ["BUILD_TIME", "SAMPLE_TEXT"]
     ```
 
-    Separate multiple values with a space.
-
-!!! tab examples "pyproject.toml"
+    In configuration files, you can use a [TOML][] list instead of a raw string as shown above.
 
-    ```toml
-    [tool.cibuildwheel.linux]
+!!! tab examples "Environment variables"
 
+    ```yaml
     # Export a variable
-    environment-pass = ["CFLAGS"]
+    CIBW_ENVIRONMENT_PASS_LINUX: CFLAGS
 
     # Set two flags variables
-    environment-pass = ["BUILD_TIME", "SAMPLE_TEXT"]
+    CIBW_ENVIRONMENT_PASS_LINUX: BUILD_TIME SAMPLE_TEXT
     ```
 
-    In configuration mode, you can use a [TOML][] list instead of a raw string as shown above.
+    Separate multiple values with a space.
 
 ### `before-all` {: #before-all env-var toml}
 > Execute a shell command on the build system before any wheels are built.
@@ -703,6 +704,8 @@ Platform-specific environment variables also available:<br/>
     ]
     ```
 
+    In configuration files, you can use a TOML array, and each line will be run sequentially - joined with `&&`.
+
 !!! tab examples "Environment variables"
 
     ```yaml
@@ -724,12 +727,10 @@ Platform-specific environment variables also available:<br/>
     here.](https://yaml-multiline.info).
 
 
-
-    In configuration files, you can use a TOML array, and each line will be run sequentially - joined with `&&`.
-
-Note that manylinux_2_31 builds occur inside a debian derivative docker container, where
-manylinux2014 builds occur inside a CentOS one. So for `manylinux_2_31` the `CIBW_BEFORE_ALL_LINUX` command
-must use `apt-get -y` instead.
+Note that `manylinux_2_31` builds occur inside a Debian derivative docker
+container, where `manylinux2014` builds occur inside a CentOS one. So for
+`manylinux_2_31` the `CIBW_BEFORE_ALL_LINUX` command must use `apt-get -y`
+instead.
 
 ### `before-build` {: #before-build env-var toml}
 > Execute a shell command preparing each wheel's build
@@ -770,6 +771,10 @@ Platform-specific environment variables are also available:<br/>
     before-build = "{package}/script/prepare_for_build.sh"
     ```
 
+    In configuration files, you can use a array, and the items will be joined
+    with `&&`. In TOML, using a single-quote string will avoid escapes - useful for
+    Windows paths.
+
 !!! tab examples "Environment variables"
 
     ```yaml
@@ -787,10 +792,6 @@ Platform-specific environment variables are also available:<br/>
     ```
 
 
-
-    In configuration mode, you can use a array, and the items will be joined with `&&`. In TOML, using a single-quote string will avoid escapes - useful for
-    Windows paths.
-
 !!! note
     If you need Python dependencies installed for the build, we recommend using
     `pyproject.toml`'s `build-system.requires` instead. This is an example
@@ -800,8 +801,7 @@ Platform-specific environment variables are also available:<br/>
         requires = [
             "setuptools>=42",
             "Cython",
-            "numpy==1.13.3; python_version<'3.5'",
-            "oldest-supported-numpy; python_version>='3.5'",
+            "numpy",
         ]
 
         build-backend = "setuptools.build_meta"
@@ -809,9 +809,7 @@ Platform-specific environment variables are also available:<br/>
     This [PEP 517][]/[PEP 518][] style build allows you to completely control
     the build environment in cibuildwheel, [PyPA-build][], and pip, doesn't
     force downstream users to install anything they don't need, and lets you do
-    more complex pinning (Cython, for example, requires a wheel to be built
-    with an equal or earlier version of NumPy; pinning in this way is the only
-    way to ensure your module works on all available NumPy versions).
+    more complex pinning.
 
     [PyPA-build]: https://pypa-build.readthedocs.io/en/latest/
     [PEP 517]: https://www.python.org/dev/peps/pep-0517/
@@ -841,6 +839,9 @@ Platform-specific environment variables are also available on platforms that use
     [tool.cibuildwheel]
     # Allow access to the cmake and rustc binaries in the isolated cross-build environment.
     xbuild-tools = ["cmake", "rustc"]
+
+    # No cross-build tools are required
+    xbuild-tools = []
     ```
 
 !!! tab examples "Environment variables"
@@ -848,21 +849,12 @@ Platform-specific environment variables are also available on platforms that use
     ```yaml
     # Allow access to the cmake and rustc binaries in the isolated cross-build environment.
     CIBW_XBUILD_TOOLS: cmake rustc
-    ```
 
-    ```yaml
     # No cross-build tools are required
     CIBW_XBUILD_TOOLS:
     ```
 
 
-
-    ```toml
-    [tool.cibuildwheel]
-    # No cross-build tools are required
-    xbuild-tools = []
-    ```
-
 ### `repair-wheel-command` {: #repair-wheel-command env-var toml}
 > Execute a shell command to repair each built wheel
 
@@ -946,6 +938,9 @@ Platform-specific environment variables are also available:<br/>
     ]
     ```
 
+    In configuration files, you can use an inline array, and the items will be joined with `&&`.
+
+
 !!! tab examples "Environment variables"
 
     ```yaml
@@ -977,10 +972,6 @@ Platform-specific environment variables are also available:<br/>
     ```
 
 
-
-    In configuration mode, you can use an inline array, and the items will be joined with `&&`.
-
-
 <div class="link-target" id="manylinux-image"></div>
 
 ### `manylinux-*-image`, `musllinux-*-image` {: #linux-image env-var toml}
@@ -1067,6 +1058,9 @@ Auditwheel detects the version of the manylinux / musllinux standard in the imag
     musllinux-i686-image = "quay.io/pypa/musllinux_1_1_i686:latest"
     ```
 
+    Like any other option, these can be placed in `[tool.cibuildwheel.linux]`
+    if you prefer; they have no effect on `macos` and `windows`.
+
 !!! tab examples "Environment variables"
 
     ```yaml
@@ -1092,11 +1086,6 @@ Auditwheel detects the version of the manylinux / musllinux standard in the imag
     ```
 
 
-
-    Like any other option, these can be placed in `[tool.cibuildwheel.linux]`
-    if you prefer; they have no effect on `macos` and `windows`.
-
-
 ### `container-engine` {: #container-engine env-var toml}
 > Specify the container engine to use when building Linux wheels
 
@@ -1160,7 +1149,6 @@ Options can be supplied after the name.
 
 
 
-
 ### `dependency-versions` {: #dependency-versions env-var toml}
 
 > Control the versions of the tools cibuildwheel uses
@@ -1346,6 +1334,7 @@ Platform-specific environment variables are also available:<br/>
     test-command = "python -m pytest ./tests"
     ```
 
+    In configuration files, you can use an array, and the items will be joined with `&&`.
 
 !!! tab examples "Environment variables"
 
@@ -1366,9 +1355,6 @@ Platform-specific environment variables are also available:<br/>
     CIBW_TEST_COMMAND_IOS: python -m pytest ./tests
     ```
 
-
-    In configuration files, you can use an array, and the items will be joined with `&&`.
-
 ### `before-test` {: #before-test env-var toml}
 > Execute a shell command before testing each wheel
 
@@ -1411,6 +1397,8 @@ Platform-specific environment variables are also available:<br/>
     before-test = "pip install cmake scikit-build"
     ```
 
+    In configuration files, you can use an array, and the items will be joined with `&&`.
+
 !!! tab examples "Environment variables"
 
     ```yaml
@@ -1432,10 +1420,6 @@ Platform-specific environment variables are also available:<br/>
     ```
 
 
-
-    In configuration files, you can use an array, and the items will be joined with `&&`.
-
-
 ### `test-sources` {: #test-sources env-var toml}
 > Files and folders from the source tree that are copied into an isolated tree before running the tests
 
@@ -1462,6 +1446,8 @@ Platform-specific environment variables are also available:<br/>
     test-sources = ["tests", "data/test-image.png"]
     ```
 
+    In configuration files, you can use an array, and the items will be joined with a space.
+
 !!! tab examples "Environment variables"
 
     ```yaml
@@ -1470,10 +1456,6 @@ Platform-specific environment variables are also available:<br/>
     ```
 
 
-
-    In configuration files, you can use an array, and the items will be joined with a space.
-
-
 ### `test_requires` {: #test-requires env-var toml}
 > Install Python dependencies before running the tests
 
@@ -1496,6 +1478,8 @@ Platform-specific environment variables are also available:<br/>
     test-requires = ["pytest==8.2.2", "packaging==24.1"]
     ```
 
+    In configuration files, you can use an array, and the items will be joined with a space.
+
 !!! tab examples "Environment variables"
 
     ```yaml
@@ -1506,7 +1490,6 @@ Platform-specific environment variables are also available:<br/>
     CIBW_TEST_REQUIRES: pytest==8.2.2 packaging==24.1
     ```
 
-    In configuration files, you can use an array, and the items will be joined with a space.
 
 
 ### `test-extras` {: #test-extras env-var toml}
@@ -1532,6 +1515,8 @@ Platform-specific environment variables are also available:<br/>
     test-extras = ["test", "qt"]
     ```
 
+    In configuration files, you can use an inline array, and the items will be joined with a comma.
+
 !!! tab examples "Environment variables"
 
     ```yaml
@@ -1543,9 +1528,6 @@ Platform-specific environment variables are also available:<br/>
 
 
 
-    In configuration files, you can use an inline array, and the items will be joined with a comma.
-
-
 ### `test-groups` {: #test-groups env-var toml}
 > Specify test dependencies from your project's `dependency-groups`
 
@@ -1568,6 +1550,9 @@ Platform-specific environment variables are also available:<br/>
     test-groups = ["test", "qt"]
     ```
 
+    In configuration files, you can use an inline array, and the items will be joined with a space.
+
+
 !!! tab examples "Environment variables"
 
     ```yaml
@@ -1577,10 +1562,6 @@ Platform-specific environment variables are also available:<br/>
 
     Separate multiple items with a space.
 
-
-
-    In configuration files, you can use an inline array, and the items will be joined with a space.
-
 ### `test-skip` {: #test-skip env-var toml}
 > Skip running tests on some builds
 

From b92fc1abe375c9422d4af86c5bc33008c73eb52f Mon Sep 17 00:00:00 2001
From: Henry Schreiner <henryschreineriii@gmail.com>
Date: Sun, 18 May 2025 23:04:40 -0400
Subject: [PATCH 05/19] docs: fix more refs to be toml style

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>
---
 docs/options.md | 37 +++++++++++++++++++------------------
 1 file changed, 19 insertions(+), 18 deletions(-)

diff --git a/docs/options.md b/docs/options.md
index 8623cb15c..67a94ebe2 100644
--- a/docs/options.md
+++ b/docs/options.md
@@ -46,7 +46,7 @@ This option can also be set using the [command-line option](#command-line) `--pl
 
 List of builds to build and skip. Each build has an identifier like `cp38-manylinux_x86_64` or `cp37-macosx_x86_64` - you can list specific ones to build and cibuildwheel will only build those, and/or list ones to skip and cibuildwheel won't try to build them.
 
-When both options are specified, both conditions are applied and only builds with a tag that matches `CIBW_BUILD` and does not match `CIBW_SKIP` will be built.
+When both options are specified, both conditions are applied and only builds with a tag that matches `build` and does not match `skip` will be built.
 
 When setting the options, you can use shell-style globbing syntax, as per [fnmatch](https://docs.python.org/3/library/fnmatch.html) with the addition of curly bracket syntax `{option1,option2}`, provided by [bracex](https://pypi.org/project/bracex/). All the build identifiers supported by cibuildwheel are shown below:
 
@@ -69,7 +69,7 @@ The list of supported and currently selected build identifiers can also be retri
 The format is `python_tag-platform_tag`, with tags similar to those in [PEP 425](https://www.python.org/dev/peps/pep-0425/#details).
 
 Windows arm64 platform support is experimental.
-Linux riscv64 platform support is experimental and requires an explicit opt-in through [CIBW_ENABLE](#enable).
+Linux riscv64 platform support is experimental and requires an explicit opt-in through [`enable`](#enable).
 
 See the [cibuildwheel 2 documentation](https://cibuildwheel.pypa.io/en/2.x/) for past end-of-life versions of Python.
 
@@ -144,7 +144,7 @@ See the [cibuildwheel 2 documentation](https://cibuildwheel.pypa.io/en/2.x/) for
 
     It is generally recommended to set `CIBW_BUILD` as an environment variable, though `skip`
     tends to be useful in a config file; you can statically declare that you don't
-    support PyPy, for example.
+    support a specific build, for example.
 
 <style>
   .build-id-table-marker + table {
@@ -190,10 +190,10 @@ Options:
     - `auto32`: Just the 32-bit auto archs
 - `native`: the native arch of the build machine - Matches [`platform.machine()`](https://docs.python.org/3/library/platform.html#platform.machine).
 - `all` : expands to all the architectures supported on this OS. You may want
-  to use [CIBW_BUILD](#build-skip) with this option to target specific
+  to use [`build`](#build-skip) with this option to target specific
   architectures via build selectors.
 
-Linux riscv64 platform support is experimental and requires an explicit opt-in through [CIBW_ENABLE](#enable).
+Linux riscv64 platform support is experimental and requires an explicit opt-in through [`enable`](#enable).
 
 Default: `auto`
 
@@ -205,7 +205,7 @@ Default: `auto`
 | macOS / Intel | `x86_64` | `x86_64` | `x86_64` |  |
 | macOS / Apple Silicon | `arm64` | `arm64` | `arm64` |  |
 | iOS on macOS / Intel | `x86_64_iphonesimulator` | `x86_64_iphonesimulator` | `x86_64_iphonesimulator` |  |
-| iOS on macOS / Apple Silicon | `arm64_iphonesimulator` | `arm64_iphoneos` `arm64_iphonesimulator` | `arm64_iphoneos` `arm64_iphonesimulator` |  |
+| iOS on macOS / Apple Silicon | `arm64_iphonesimulator` | `arm64_iphoneos` `arm64_iphonesimulator` | `arm64_iphoneos` `arm64_iphonesimulator` |
 
 If not listed above, `auto` is the same as `native`.
 
@@ -305,7 +305,7 @@ the package is compatible with all versions of Python that it can build.
     CIBW_PROJECT_REQUIRES_PYTHON: ">=3.8"
     ```
 
-###  `CIBW_ENABLE` {: #enable toml env-var}
+### `enable` {: #enable toml env-var}
 > Enable building with extra categories of selectors present.
 
 This option lets you opt-in to non-default builds, like pre-releases and
@@ -347,7 +347,7 @@ This option doesn't support overrides or platform specific variants; it is
 intended as a way to acknowledge that a project is aware that these extra
 selectors exist.  If you need to enable/disable it per platform or python
 version, set this option to `true` and use
-[`CIBW_BUILD`](#build-skip)/[`CIBW_SKIP`](#build-skip) options to filter the
+[`build`](#build-skip)/[`skip`](#build-skip) options to filter the
 builds.
 
 Unlike all other cibuildwheel options, the environment variable setting will
@@ -671,7 +671,7 @@ This option is very useful for the Linux build, where builds take place in isola
 
 The placeholder `{package}` can be used here; it will be replaced by the path to the package being built by cibuildwheel.
 
-On Windows and macOS, the version of Python available inside `CIBW_BEFORE_ALL` is whatever is available on the host machine. On Linux, a modern Python version is available on PATH.
+On Windows and macOS, the version of Python available inside `before-all` is whatever is available on the host machine. On Linux, a modern Python version is available on PATH.
 
 This option has special behavior in the overrides section in `pyproject.toml`.
 On linux, overriding it triggers a new container launch. It cannot be overridden
@@ -682,7 +682,7 @@ Platform-specific environment variables also available:<br/>
 
 !!! note
 
-    This command is executed in a different Python environment from the builds themselves. So you can't `pip install` a Python dependency in CIBW_BEFORE_ALL and use it in the build. Instead, look at [`CIBW_BEFORE_BUILD`](#before-build), or, if your project uses pyproject.toml, the [build-system.requires](https://peps.python.org/pep-0518/#build-system-table) field.
+    This command is executed in a different Python environment from the builds themselves. So you can't `pip install` a Python dependency in `before-all` and use it in the build. Instead, look at [`before-build`](#before-build), or, if your project uses pyproject.toml, the [build-system.requires](https://peps.python.org/pep-0518/#build-system-table) field.
 
 #### Examples
 
@@ -729,7 +729,7 @@ Platform-specific environment variables also available:<br/>
 
 Note that `manylinux_2_31` builds occur inside a Debian derivative docker
 container, where `manylinux2014` builds occur inside a CentOS one. So for
-`manylinux_2_31` the `CIBW_BEFORE_ALL_LINUX` command must use `apt-get -y`
+`manylinux_2_31` the `before-all` command must use `apt-get -y`
 instead.
 
 ### `before-build` {: #before-build env-var toml}
@@ -820,13 +820,13 @@ Platform-specific environment variables are also available:<br/>
 
 When building in a cross-platform environment, it is sometimes necessary to isolate the ``PATH`` so that binaries from the build machine don't accidentally get linked into the cross-platform binary. However, this isolation process will also hide tools that might be required to build your wheel.
 
-If there are binaries present on the `PATH` when you invoke cibuildwheel, and those binaries are required to build your wheels, those binaries can be explicitly included in the isolated cross-build environment using `CIBW_XBUILD_TOOLS`. The binaries listed in this setting will be linked into an isolated location, and that isolated location will be put on the `PATH` of the isolated environment. You do not need to provide the full path to the binary - only the executable name that would be found by the shell.
+If there are binaries present on the `PATH` when you invoke cibuildwheel, and those binaries are required to build your wheels, those binaries can be explicitly included in the isolated cross-build environment using `xbuild-tools`. The binaries listed in this setting will be linked into an isolated location, and that isolated location will be put on the `PATH` of the isolated environment. You do not need to provide the full path to the binary - only the executable name that would be found by the shell.
 
 If you declare a tool as a cross-build tool, and that tool cannot be found in the runtime environment, an error will be raised.
 
-If you do not define `CIBW_XBUILD_TOOLS`, and you build for a platform that uses a cross-platform environment, a warning will be raised. If your project does not require any cross-build tools, you can set `CIBW_XBUILD_TOOLS` to an empty list to silence this warning.
+If you do not define `xbuild-tools`, and you build for a platform that uses a cross-platform environment, a warning will be raised. If your project does not require any cross-build tools, you can set `xbuild-tools` to an empty list to silence this warning.
 
-*Any* tool used by the build process must be included in the `CIBW_XBUILD_TOOLS` list, not just tools that cibuildwheel will invoke directly. For example, if your build invokes `cmake`, and the `cmake` script invokes `magick` to perform some image transformations, both `cmake` and `magick` must be included in your safe tools list.
+*Any* tool used by the build process must be included in the `xbuild-tools` list, not just tools that cibuildwheel will invoke directly. For example, if your build invokes `cmake`, and the `cmake` script invokes `magick` to perform some image transformations, both `cmake` and `magick` must be included in your safe tools list.
 
 Platform-specific environment variables are also available on platforms that use cross-platform environment isolation:<br/>
  `CIBW_XBUILD_TOOLS_IOS`
@@ -1297,7 +1297,7 @@ Using `{package}` or `{project}` used to be required, but since cibuildwheel
 use relative paths in your test command, and they will be relative to the
 project root.
 
-Alternatively, you can use the [`test_sources`](#test-sources) setting to
+Alternatively, you can use the [`test-sources`](#test-sources) setting to
 create a temporary folder populated with a specific subset of project files to
 run your test suite.
 
@@ -1456,7 +1456,7 @@ Platform-specific environment variables are also available:<br/>
     ```
 
 
-### `test_requires` {: #test-requires env-var toml}
+### `test-requires` {: #test-requires env-var toml}
 > Install Python dependencies before running the tests
 
 Space-separated list of dependencies required for running the tests.
@@ -1469,7 +1469,7 @@ Platform-specific environment variables are also available:<br/>
 !!! tab examples "pyproject.toml"
 
     ```toml
-    # Install pytest before running CIBW_TEST_COMMAND
+    # Install pytest before running test-command
     [tool.cibuildwheel]
     test-requires = "pytest"
 
@@ -1565,7 +1565,7 @@ Platform-specific environment variables are also available:<br/>
 ### `test-skip` {: #test-skip env-var toml}
 > Skip running tests on some builds
 
-This will skip testing on any identifiers that match the given skip patterns (see [`CIBW_SKIP`](#build-skip)). This can be used to mask out tests for wheels that have missing dependencies upstream that are slow or hard to build, or to skip slow tests on emulated architectures.
+This will skip testing on any identifiers that match the given skip patterns (see [`skip`](#build-skip)). This can be used to mask out tests for wheels that have missing dependencies upstream that are slow or hard to build, or to skip slow tests on emulated architectures.
 
 With macOS `universal2` wheels, you can also skip the individual archs inside the wheel using an `:arch` suffix. For example, `cp39-macosx_universal2:x86_64` or `cp39-macosx_universal2:arm64`.
 
@@ -1639,6 +1639,7 @@ Platform-specific environment variables are also available:<br/>
 ## Debugging
 
 ### `CIBW_DEBUG_KEEP_CONTAINER` {: #debug-keep-container env-var}
+> Keep the container after running for debugging.
 
 Enable this flag to keep the container around for inspection after a build. This
 option is provided for debugging purposes only.

From 1365071c7e8fba19796a884ae13a0a4718154540 Mon Sep 17 00:00:00 2001
From: Henry Schreiner <henryschreineriii@gmail.com>
Date: Tue, 20 May 2025 17:09:18 -0400
Subject: [PATCH 06/19] docs: include pyodide-version in reordering

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>
---
 docs/options.md | 23 ++++++++++++-----------
 1 file changed, 12 insertions(+), 11 deletions(-)

diff --git a/docs/options.md b/docs/options.md
index 67a94ebe2..8f6010833 100644
--- a/docs/options.md
+++ b/docs/options.md
@@ -1234,7 +1234,7 @@ Platform-specific environment variables are also available:<br/>
 
 
 
-### `CIBW_PYODIDE_VERSION` {: #pyodide-version}
+### `pyodide-version` {: #pyodide-version toml env-var }
 
 > Specify the Pyodide version to use for `pyodide` platform builds
 
@@ -1248,18 +1248,9 @@ This option is particularly useful for:
 The available Pyodide versions are determined by the version of `pyodide-build` being used. You can list the compatible versions using the command `pyodide xbuildenv search --all` as described in the [Pyodide platform documentation](platforms.md#pyodide-choosing-a-version).
 
 !!! tip
-    You can set the version of `pyodide-build` using the [`CIBW_DEPENDENCY_VERSIONS`](#dependency-versions) option.
+    You can set the version of `pyodide-build` using the [`dependency-versions`](#dependency-versions) option.
 
 #### Examples
-
-!!! tab examples "Environment variables"
-
-    ```yaml
-    # Build Pyodide wheels using Pyodide version 0.27.6
-    CIBW_PYODIDE_VERSION: 0.27.6
-
-    # Build Pyodide wheels using a specific alpha release
-    CIBW_PYODIDE_VERSION: 0.28.0a2
     ```
 
 !!! tab examples "pyproject.toml"
@@ -1274,6 +1265,16 @@ The available Pyodide versions are determined by the version of `pyodide-build`
     pyodide-version = "0.28.0a2"
     ```
 
+!!! tab examples "Environment variables"
+
+    ```yaml
+    # Build Pyodide wheels using Pyodide version 0.27.6
+    CIBW_PYODIDE_VERSION: 0.27.6
+
+    # Build Pyodide wheels using a specific alpha release
+    CIBW_PYODIDE_VERSION: 0.28.0a2
+
+
 ## Testing
 
 ### `test-command` {: #test-command env-var toml}

From 258d4cdf065f0cbc0a77654dfad14099acdac2cf Mon Sep 17 00:00:00 2001
From: Henry Schreiner <HenrySchreinerIII@gmail.com>
Date: Wed, 21 May 2025 05:04:07 -0400
Subject: [PATCH 07/19] Apply suggestions from code review

Co-authored-by: Matthieu Darbois <mayeut@users.noreply.github.com>
---
 docs/options.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/options.md b/docs/options.md
index 8f6010833..5e8021eaf 100644
--- a/docs/options.md
+++ b/docs/options.md
@@ -1251,7 +1251,6 @@ The available Pyodide versions are determined by the version of `pyodide-build`
     You can set the version of `pyodide-build` using the [`dependency-versions`](#dependency-versions) option.
 
 #### Examples
-    ```
 
 !!! tab examples "pyproject.toml"
 
@@ -1273,6 +1272,7 @@ The available Pyodide versions are determined by the version of `pyodide-build`
 
     # Build Pyodide wheels using a specific alpha release
     CIBW_PYODIDE_VERSION: 0.28.0a2
+    ```
 
 
 ## Testing

From 095f556cf8e37df355d0d781b0643741277e00f8 Mon Sep 17 00:00:00 2001
From: Henry Schreiner <henryschreineriii@gmail.com>
Date: Thu, 22 May 2025 00:02:03 -0400
Subject: [PATCH 08/19] docs: use all lowercase

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>
---
 docs/options.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/options.md b/docs/options.md
index 5e8021eaf..fd4f0f191 100644
--- a/docs/options.md
+++ b/docs/options.md
@@ -255,7 +255,7 @@ This option can also be set using the [command-line option](#command-line)
     on your specific runner having qemu installed.
 
 
-###  `CIBW_PROJECT_REQUIRES_PYTHON` {: #requires-python env-var}
+###  `project-requires-python` {: #requires-python env-var}
 > Manually set the Python compatibility of your project
 
 By default, cibuildwheel reads your package's Python compatibility from
@@ -397,7 +397,7 @@ without disabling your other enables.
 
 
 
-### `CIBW_ALLOW_EMPTY` {: #allow-empty cmd-line env-var}
+### `allow-empty` {: #allow-empty cmd-line env-var}
 > Suppress the error code if no wheels match the specified build identifiers
 
 When none of the specified build identifiers match any available versions,
@@ -1639,7 +1639,7 @@ Platform-specific environment variables are also available:<br/>
 
 ## Debugging
 
-### `CIBW_DEBUG_KEEP_CONTAINER` {: #debug-keep-container env-var}
+### `debug-keep-container` {: #debug-keep-container env-var}
 > Keep the container after running for debugging.
 
 Enable this flag to keep the container around for inspection after a build. This
@@ -1656,7 +1656,7 @@ Default: Off (0).
 export CIBW_DEBUG_KEEP_CONTAINER=TRUE
 ```
 
-### `CIBW_DEBUG_TRACEBACK` {: #debug-traceback cmd-line env-var}
+### `debug-traceback` {: #debug-traceback cmd-line env-var}
 > Print full traceback when errors occur.
 
 Print a full traceback for the cibuildwheel process when errors occur. This

From cfff35303cd0da0cf3b137e4dd2023802e0fbbb7 Mon Sep 17 00:00:00 2001
From: Henry Schreiner <henryschreineriii@gmail.com>
Date: Thu, 22 May 2025 00:11:47 -0400
Subject: [PATCH 09/19] docs: fix missing CIBW

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>
---
 docs/options.md | 12 ++++--------
 1 file changed, 4 insertions(+), 8 deletions(-)

diff --git a/docs/options.md b/docs/options.md
index fd4f0f191..ee2524caf 100644
--- a/docs/options.md
+++ b/docs/options.md
@@ -1908,13 +1908,6 @@ Some options support placeholders, like `{project}`, `{package}` or `{wheel}`, t
         el.classList.add('option', 'clearfix');
         var optionName = $(el).text().replace('¶', '');
 
-        // some options are specified as their env var names
-        if (optionName.startsWith('CIBW_')) {
-          optionName = optionName.replace('CIBW_', '');
-          optionName = optionName.replace(/_/g, '-');
-          optionName = optionName.toLowerCase();
-        }
-
         var cmdLine = el.getAttribute('cmd-line');
         var envVar = el.getAttribute('env-var');
         var toml = el.getAttribute('toml');
@@ -1924,7 +1917,10 @@ Some options support placeholders, like `{project}`, `{package}` or `{wheel}`, t
           cmdLine = '--'+optionName;
         }
         if (envVar == "env-var") {
-          envVar = 'CIBW_'+optionName.toUpperCase().replace(/-/g, '_');
+          envVar = optionName
+            .split(', ')
+            .map(opt => 'CIBW_'+opt.toUpperCase().replace(/-/g, '_'))
+            .join(', ');
         }
         if (toml == "toml") {
           toml = optionName

From 2709b40f440f2527dbd3e1173a22e490ff73192d Mon Sep 17 00:00:00 2001
From: mayeut <mayeut@users.noreply.github.com>
Date: Sun, 25 May 2025 14:06:16 +0200
Subject: [PATCH 10/19] docs: revert order of toml & environment variables in
 "getting started"

---
 docs/setup.md | 36 ++++++++++++++++++------------------
 1 file changed, 18 insertions(+), 18 deletions(-)

diff --git a/docs/setup.md b/docs/setup.md
index c13fb972f..03a13491b 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -23,7 +23,24 @@ cibuildwheel
 !!!tip
     You can pass the `--platform linux` option to cibuildwheel to build Linux wheels, even if you're not on Linux. On most machines, the easiest builds to try are the Linux builds. You don't need any software installed except a Docker daemon, such as [Docker Desktop](https://www.docker.com/get-started/). Each platform that cibuildwheel supports has its own system requirements and platform-specific behaviors. See the [platforms page](platforms.md) for details.
 
-You should see the builds taking place. You can experiment with [options](options.md) using environment variables or pyproject.toml.
+You should see the builds taking place. You can experiment with [options](options.md) using pyproject.toml or environment variables.
+
+!!! tab "pyproject.toml"
+
+    If you write your options into [`pyproject.toml`](configuration.md#configuration-file), you can work on your options locally, and they'll be automatically picked up when running in CI.
+
+    > pyproject.toml
+
+    ```
+    [tool.cibuildwheel]
+    before-all = "uname -a"
+    ```
+
+    Then invoke cibuildwheel, like:
+
+    ```console
+    cibuildwheel
+    ```
 
 !!! tab "Environment variables"
 
@@ -46,23 +63,6 @@ You should see the builds taking place. You can experiment with [options](option
     cibuildwheel
     ```
 
-!!! tab "pyproject.toml"
-
-    If you write your options into [`pyproject.toml`](configuration.md#configuration-file), you can work on your options locally, and they'll be automatically picked up when running in CI.
-
-    > pyproject.toml
-
-    ```
-    [tool.cibuildwheel]
-    before-all = "uname -a"
-    ```
-
-    Then invoke cibuildwheel, like:
-
-    ```console
-    cibuildwheel
-    ```
-
 - Once you've got a build working locally, you can move on to [setting up a CI service](ci-services.md).
 - View the [full options reference](options.md) to see what cibuildwheel can do.
 - Check out the [FAQ](faq.md) for common questions.

From ba13fc38e69c1f40e6dfdb7ad433e5ce90e17686 Mon Sep 17 00:00:00 2001
From: Joe Rickerby <joerick@mac.com>
Date: Sun, 25 May 2025 16:33:38 +0100
Subject: [PATCH 11/19] Improve formatting of the build/skip table and big
 tables in general

---
 docs/extra.css  | 31 +++++++++++++++++++++++++++++++
 docs/options.md | 17 +++++++++++------
 2 files changed, 42 insertions(+), 6 deletions(-)

diff --git a/docs/extra.css b/docs/extra.css
index c8f0953b4..051a518b8 100644
--- a/docs/extra.css
+++ b/docs/extra.css
@@ -47,6 +47,37 @@ h1, h2, h3, h4, h5, h6 {
     padding-bottom: 0.2em;
 }
 
+/* make it so tables can overflow the content area, make the most of the content area */
+.wy-nav-content-wrap {
+  container-type: inline-size;
+}
+.wy-table-responsive {
+  overflow-x: auto;
+  overflow-y: hidden;
+  position: relative;
+  left: -3.236em;
+  max-width: calc(100cqw);
+  width: fit-content;
+  min-width: 100%;
+}
+.rst-content .section .wy-table-responsive .docutils {
+  padding-left: 3.236em;
+  padding-right: 3.236em;
+}
+.rst-content .section .wy-table-responsive .docutils thead,
+.rst-content .section .wy-table-responsive .docutils tbody {
+  background-color: white;
+}
+@media screen and (max-width: 768px) {
+  .wy-table-responsive {
+    left: -1em;
+  }
+  .rst-content .section .wy-table-responsive .docutils {
+    padding-left: 1em;
+    padding-right: 1em;
+  }
+}
+
 .wy-nav-content {
   max-width: 900px;
 }
diff --git a/docs/options.md b/docs/options.md
index ee2524caf..4d51f3bbd 100644
--- a/docs/options.md
+++ b/docs/options.md
@@ -147,18 +147,23 @@ See the [cibuildwheel 2 documentation](https://cibuildwheel.pypa.io/en/2.x/) for
     support a specific build, for example.
 
 <style>
-  .build-id-table-marker + table {
+  .build-id-table-marker + .wy-table-responsive table {
     font-size: 90%;
-    white-space: nowrap;
   }
-  .rst-content .build-id-table-marker + table td,
-  .rst-content .build-id-table-marker + table th {
-    padding: 4px 4px;
+  .rst-content .build-id-table-marker + .wy-table-responsive table td,
+  .rst-content .build-id-table-marker + .wy-table-responsive table th {
+    padding: 4px 8px;
+    white-space: nowrap;
+    background-color: white;
   }
-  .build-id-table-marker + table td:not(:first-child) {
+  .build-id-table-marker + .wy-table-responsive table td:not(:first-child) {
     font-family: SFMono-Regular, Consolas, Liberation Mono, Menlo, monospace;
     font-size: 85%;
   }
+  .build-id-table-marker + .wy-table-responsive table td:first-child,
+  .build-id-table-marker + .wy-table-responsive table th:first-child {
+    font-weight: bold;
+  }
   dt code {
     font-size: 100%;
     background-color: rgba(41, 128, 185, 0.1);

From 71d84dcbffbcf356d286cc0fc096d6bfbeda43ed Mon Sep 17 00:00:00 2001
From: Joe Rickerby <joerick@mac.com>
Date: Sun, 25 May 2025 16:39:06 +0100
Subject: [PATCH 12/19] Add graalpy to the build identifiers page

---
 docs/options.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/options.md b/docs/options.md
index 4d51f3bbd..c35721ecf 100644
--- a/docs/options.md
+++ b/docs/options.md
@@ -64,6 +64,7 @@ When setting the options, you can use shell-style globbing syntax, as per [fnmat
 | PyPy3.9 v7.3  | pp39-macosx_x86_64<br/>pp39-macosx_arm64                               | pp39-win_amd64                                      | pp39-manylinux_x86_64<br/>pp39-manylinux_i686                                                       | pp39-manylinux_aarch64                                                                                                                                                                                                                                                        |                                                                                                   |                      |
 | PyPy3.10 v7.3 | pp310-macosx_x86_64<br/>pp310-macosx_arm64                             | pp310-win_amd64                                     | pp310-manylinux_x86_64<br/>pp310-manylinux_i686                                                     | pp310-manylinux_aarch64                                                                                                                                                                                                                                                       |                                                                                                   |                      |
 | PyPy3.11 v7.3 | pp311-macosx_x86_64<br/>pp311-macosx_arm64                             | pp311-win_amd64                                     | pp311-manylinux_x86_64<br/>pp311-manylinux_i686                                                     | pp311-manylinux_aarch64                                                                                                                                                                                                                                                       |                                                                                                   |                      |
+| GraalPy v24.2 | gp242-macosx_x86_64<br/>gp242-macosx_arm64                             | gp242-win_amd64                                     | gp242-manylinux_x86_64                                                                              | gp242-manylinux_aarch64                                                                                                                                                                                                                                                       |                                                                                                   |                      |
 
 The list of supported and currently selected build identifiers can also be retrieved by passing the `--print-build-identifiers` flag to cibuildwheel.
 The format is `python_tag-platform_tag`, with tags similar to those in [PEP 425](https://www.python.org/dev/peps/pep-0425/#details).

From 78cee0e6c563909b2bf5d88f1dc099106b09d265 Mon Sep 17 00:00:00 2001
From: Joe Rickerby <joerick@mac.com>
Date: Sun, 25 May 2025 17:26:12 +0100
Subject: [PATCH 13/19] Improve scroll target positioning

---
 docs/extra.css | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/extra.css b/docs/extra.css
index 051a518b8..62bd7ff28 100644
--- a/docs/extra.css
+++ b/docs/extra.css
@@ -45,6 +45,7 @@ h1, h2, h3, h4, h5, h6 {
     border-bottom: 1px solid  #e1e4e5;
     margin-bottom: 0.8em;
     padding-bottom: 0.2em;
+    scroll-margin: 1.5em 0;
 }
 
 /* make it so tables can overflow the content area, make the most of the content area */

From d6559159ce9a65cc5c1750391dd475ab89b460dd Mon Sep 17 00:00:00 2001
From: Joe Rickerby <joerick@mac.com>
Date: Sun, 25 May 2025 17:26:56 +0100
Subject: [PATCH 14/19] Fix the outdated examples for `build-frontend`

---
 docs/options.md | 10 ++--------
 1 file changed, 2 insertions(+), 8 deletions(-)

diff --git a/docs/options.md b/docs/options.md
index c35721ecf..134bd60d9 100644
--- a/docs/options.md
+++ b/docs/options.md
@@ -470,10 +470,7 @@ optional `args` option.
 
     ```toml
     [tool.cibuildwheel]
-    # Switch to using build
-    build-frontend = "build"
-
-    # Ensure pip is used even if the default changes in the future
+    # Switch to using pip
     build-frontend = "pip"
 
     # supply an extra argument to 'pip wheel'
@@ -489,10 +486,7 @@ optional `args` option.
 !!! tab examples "Environment variables"
 
     ```yaml
-    # Switch to using build
-    CIBW_BUILD_FRONTEND: "build"
-
-    # Ensure pip is used even if the default changes in the future
+    # Switch to using pip
     CIBW_BUILD_FRONTEND: "pip"
 
     # supply an extra argument to 'pip wheel'

From 41c7bdb9eddfaae9b91e9f184897d354052c6c9e Mon Sep 17 00:00:00 2001
From: Joe Rickerby <joerick@mac.com>
Date: Sun, 25 May 2025 17:27:34 +0100
Subject: [PATCH 15/19] Fix non-options appearing in options summary, style
 options in sidebar

---
 docs/options.md | 24 ++++++++++++++++++++++--
 1 file changed, 22 insertions(+), 2 deletions(-)

diff --git a/docs/options.md b/docs/options.md
index 134bd60d9..a08386e99 100644
--- a/docs/options.md
+++ b/docs/options.md
@@ -40,7 +40,7 @@ This option can also be set using the [command-line option](#command-line) `--pl
     not require `--platform` or `--arch`, and will override any build/skip
     configuration.
 
-### `build` & `skip` {: #build-skip toml="build, skip" env-var="CIBW_BUILD, CIBW_SKIP" }
+### `build`, `skip` {: #build-skip toml env-var }
 
 > Choose the Python versions to build
 
@@ -1740,6 +1740,7 @@ Specific error codes are defined:
 Some options support placeholders, like `{project}`, `{package}` or `{wheel}`, that are substituted by cibuildwheel before they are used. If, for some reason, you need to write the literal name of a placeholder, e.g. literally `{project}` in a command that would ordinarily substitute `{project}`, prefix it with a hash character - `#{project}`. This is only necessary in commands where the specific string between the curly brackets would be substituted - otherwise, strings not modified.
 
 <style>
+  /* Table of contents styling */
   .options-toc {
     display: grid;
     grid-template-columns: fit-content(20%) 1fr;
@@ -1770,6 +1771,8 @@ Some options support placeholders, like `{project}`, `{package}` or `{wheel}`, t
   .options-toc a.option code {
     font-size: 80%;
   }
+
+  /* header styling, including the badges */
   .rst-content h3 code {
     font-size: 115%;
   }
@@ -1813,6 +1816,10 @@ Some options support placeholders, like `{project}`, `{package}` or `{wheel}`, t
   .rst-content h3 code.env-var {
     background: rgba(61, 153, 112, 0.3);
   }
+  /* sidebar TOC styling */
+  .toctree-l3.option a {
+    font-family: SFMono-Regular, Consolas, Liberation Mono, Menlo, monospace;
+  }
 </style>
 
 <script>
@@ -1828,11 +1835,15 @@ Some options support placeholders, like `{project}`, `{package}` or `{wheel}`, t
         var header = $(el).prevAll('h2').first().text().replace('¶', '')
         var id = el.id;
 
+        if (optionName[0].match(/[A-Z]/)) {
+          // all the options are kebab-case, so this header isn't an option
+          return;
+        }
+
         if (options[header] === undefined) {
           options[header] = [];
           headers.push(header);
         }
-        console.log(optionName, description, header);
 
         options[header].push({name: optionName, description, id});
       });
@@ -1936,6 +1947,15 @@ Some options support placeholders, like `{project}`, `{package}` or `{wheel}`, t
           $(el).append(' <code class="cmd-line" title="Command line argument">'+cmdLine+'</code>');
         }
       });
+
+    $('.toctree-l3')
+      .each(function (i, el) {
+        var tocEntryName = $(el).text()
+        var isOption = tocEntryName[0].match(/^[a-z]/);
+        if (isOption) {
+          $(el).addClass('option');
+        }
+      });
   });
 
 </script>

From 14dd6104810b8ca94e37d3061c8441e0fdeeec2e Mon Sep 17 00:00:00 2001
From: Joe Rickerby <joerick@mac.com>
Date: Sun, 25 May 2025 17:41:12 +0100
Subject: [PATCH 16/19] build-frontend isn't available as a command-line option

---
 docs/options.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/options.md b/docs/options.md
index a08386e99..58f98adb6 100644
--- a/docs/options.md
+++ b/docs/options.md
@@ -427,7 +427,7 @@ This option can also be set using the [command-line option](#command-line)
 
 ## Build customization
 
-### `build-frontend` {: #build-frontend cmd-line toml env-var}
+### `build-frontend` {: #build-frontend toml env-var}
 > Set the tool to use to build, either "build" (default), "build\[uv\]", or "pip"
 
 Options:

From c43fa3be60b92efb60a341d607fa4cc42c78d083 Mon Sep 17 00:00:00 2001
From: Joe Rickerby <joerick@mac.com>
Date: Sun, 25 May 2025 17:52:58 +0100
Subject: [PATCH 17/19] Fix the layout of badges into a flexbox, to prevent
 strange floats

---
 docs/options.md | 49 +++++++++++++++++++++++++++++++++----------------
 1 file changed, 33 insertions(+), 16 deletions(-)

diff --git a/docs/options.md b/docs/options.md
index 58f98adb6..3ade43d93 100644
--- a/docs/options.md
+++ b/docs/options.md
@@ -1776,10 +1776,20 @@ Some options support placeholders, like `{project}`, `{package}` or `{wheel}`, t
   .rst-content h3 code {
     font-size: 115%;
   }
-  .rst-content h3 code.cmd-line, .rst-content h3 code.toml, .rst-content h3 code.env-var {
-    font-size: 80%;
+  .rst-content h3 .badges {
+    display: inline-flex;
+    justify-content: right;
+    flex-wrap: wrap;
+    flex-direction: row;
     float: right;
-    margin-left: 8px;
+    width: fit-content;
+    max-width: 100%;
+    gap: 2px 2px;
+    position: relative;
+    top: 2px;
+  }
+  .rst-content h3 .badges code.cmd-line, .rst-content h3 .badges code.toml, .rst-content h3 .badges code.env-var {
+    font-size: 80%;
     display: inline-flex;
     flex-direction: column;
     justify-content: left;
@@ -1787,33 +1797,33 @@ Some options support placeholders, like `{project}`, `{package}` or `{wheel}`, t
     padding-right: 10px;
     line-height: normal;
   }
-  .rst-content h3 code.cmd-line:before, .rst-content h3 code.toml:before, .rst-content h3 code.env-var:before {
+  .rst-content h3 .badges code.cmd-line:before, .rst-content h3 .badges code.toml:before, .rst-content h3 .badges code.env-var:before {
     content: ' ';
     font-size: 10px;
     font-weight: bold;
-    opacity: 0.3;
+    opacity: 0.5;
     display: inline-block;
     border-radius: 5px;
     margin-left: -3px;
     margin-right: -3px;
     margin-bottom: -1px;
   }
-  .rst-content h3 code.cmd-line:before {
+  .rst-content h3 .badges code.cmd-line:before {
     content: 'command line';
   }
-  .rst-content h3 code.cmd-line {
+  .rst-content h3 .badges code.cmd-line {
     background: rgba(224, 202, 56, 0.3);
   }
-  .rst-content h3 code.toml:before {
+  .rst-content h3 .badges code.toml:before {
     content: 'pyproject.toml';
   }
-  .rst-content h3 code.toml {
+  .rst-content h3 .badges code.toml {
     background: rgba(41, 128, 185, 0.3);
   }
-  .rst-content h3 code.env-var:before {
+  .rst-content h3 .badges code.env-var:before {
     content: 'env var';
   }
-  .rst-content h3 code.env-var {
+  .rst-content h3 .badges code.env-var {
     background: rgba(61, 153, 112, 0.3);
   }
   /* sidebar TOC styling */
@@ -1923,6 +1933,13 @@ Some options support placeholders, like `{project}`, `{package}` or `{wheel}`, t
         var envVar = el.getAttribute('env-var');
         var toml = el.getAttribute('toml');
 
+        if (!(cmdLine || envVar || toml)) {
+          return;
+        }
+
+        var badgesEl = $('<div class="badges">')
+          .appendTo(el);
+
         // fill default value
         if (cmdLine == "cmd-line") {
           cmdLine = '--'+optionName;
@@ -1937,14 +1954,14 @@ Some options support placeholders, like `{project}`, `{package}` or `{wheel}`, t
           toml = optionName
         }
 
-        if (envVar) {
-          $(el).append(' <code class="env-var" title="Environment variable">'+envVar+'</code>');
-        }
         if (toml) {
-          $(el).append(' <code class="toml" title="TOML option key">'+toml+'</code>');
+          badgesEl.append(' <code class="toml" title="TOML option key">'+toml+'</code>');
         }
         if (cmdLine) {
-          $(el).append(' <code class="cmd-line" title="Command line argument">'+cmdLine+'</code>');
+          badgesEl.append(' <code class="cmd-line" title="Command line argument">'+cmdLine+'</code>');
+        }
+        if (envVar) {
+          badgesEl.append(' <code class="env-var" title="Environment variable">'+envVar+'</code>');
         }
       });
 

From 99a3c0585832b043a6010c5c825779d60fe9481d Mon Sep 17 00:00:00 2001
From: Joe Rickerby <joerick@mac.com>
Date: Sun, 25 May 2025 17:53:14 +0100
Subject: [PATCH 18/19] Fix table appearance on working-examples page

---
 docs/working-examples.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/docs/working-examples.md b/docs/working-examples.md
index facc03ba0..e9684a880 100644
--- a/docs/working-examples.md
+++ b/docs/working-examples.md
@@ -253,4 +253,10 @@ title: Working examples
   /* make the icons darker on this page */
   filter: brightness(0.5);
 }
+@media screen and (min-width: 769px) {
+  .wy-table-responsive {
+    /* disable the table overflow */
+    width: calc(100% + 6em);
+  }
+}
 </style>

From 0c59eca03f35e6bc1eb80d651a3309db48734235 Mon Sep 17 00:00:00 2001
From: Joe Rickerby <joerick@mac.com>
Date: Sun, 25 May 2025 17:58:46 +0100
Subject: [PATCH 19/19] Improve table formatting

---
 docs/extra.css           | 2 +-
 docs/working-examples.md | 6 ------
 2 files changed, 1 insertion(+), 7 deletions(-)

diff --git a/docs/extra.css b/docs/extra.css
index 62bd7ff28..ecd99f667 100644
--- a/docs/extra.css
+++ b/docs/extra.css
@@ -59,7 +59,7 @@ h1, h2, h3, h4, h5, h6 {
   left: -3.236em;
   max-width: calc(100cqw);
   width: fit-content;
-  min-width: 100%;
+  min-width: calc(100% + 3.236em + 3.236em);
 }
 .rst-content .section .wy-table-responsive .docutils {
   padding-left: 3.236em;
diff --git a/docs/working-examples.md b/docs/working-examples.md
index e9684a880..facc03ba0 100644
--- a/docs/working-examples.md
+++ b/docs/working-examples.md
@@ -253,10 +253,4 @@ title: Working examples
   /* make the icons darker on this page */
   filter: brightness(0.5);
 }
-@media screen and (min-width: 769px) {
-  .wy-table-responsive {
-    /* disable the table overflow */
-    width: calc(100% + 6em);
-  }
-}
 </style>