docs: fix more issues, normalize a bit

Signed-off-by: Henry Schreiner <[email protected]>

Author: henryiii

docs/options.md

@@ -354,7 +354,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
@@ -369,6 +371,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"]
     ```
 
 
@@ -387,15 +392,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}
@@ -588,6 +589,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
@@ -617,8 +620,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).
 
@@ -637,31 +638,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.
@@ -705,6 +706,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
@@ -726,12 +729,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
@@ -772,6 +773,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
@@ -789,10 +794,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
@@ -802,18 +803,15 @@ 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"
 
     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/
@@ -843,28 +841,22 @@ 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"
 
     ```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
 
@@ -948,6 +940,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
@@ -979,10 +974,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}
@@ -1069,6 +1060,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
@@ -1094,11 +1088,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
 
@@ -1162,7 +1151,6 @@ Options can be supplied after the name.
 
 
 
-
 ### `dependency-versions` {: #dependency-versions env-var toml}
 
 > Control the versions of the tools cibuildwheel uses
@@ -1302,6 +1290,9 @@ Platform-specific environment variables are also available:<br/>
     ]
     ```
 
+    In configuration files, you can use an array, and the items will be joined with `&&`.
+
+
 !!! tab examples "Environment variables"
 
     ```yaml
@@ -1318,9 +1309,6 @@ Platform-specific environment variables are also available:<br/>
     ```
 
 
-
-    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
 
@@ -1363,6 +1351,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
@@ -1384,10 +1374,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
 
@@ -1414,6 +1400,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
@@ -1422,10 +1410,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
 
@@ -1448,6 +1432,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
@@ -1458,7 +1444,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}
@@ -1484,6 +1469,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
@@ -1495,9 +1482,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`
 
@@ -1520,6 +1504,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
@@ -1529,10 +1516,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