Add method to keep build isolation in CI guide (#58)

docs/ci.md

@@ -27,8 +27,22 @@ for building free-threaded wheels on all platforms. If your project releases
 nightly wheels, we suggest configuring `cibuildwheel` to build nightly
 free-threaded wheels.
 
-You will need to specify the following variables in the environment for the
-cibuildwheel action:
+If your project depends on Cython or the NumPy C API, you will need to install a
+Cython and/or NumPy nightly wheel in the build, as the newest stable release of
+Cython cannot generate code that will compile under the free-threaded build and
+the newest stable release of NumPy does not support free-threaded python. Cython
+3.1.0 and NumPy 2.1.0 will be the first stable releases to support free-threaded
+python.
+
+You can install nightly wheels for both Cython and NumPy using the following
+install command:
+
+```bash
+pip install -i https://pypi.anaconda.org/scientific-python-nightly-wheels/simple cython numpy
+```
+
+To ensure wheels are built correctly under cibuildwheel, you will need to
+specify the following variables in the environment for the cibuildwheel action:
 
 ```yaml
   - name: Build wheels
@@ -37,25 +51,29 @@ cibuildwheel action:
       CIBW_PRERELEASE_PYTHONS: true
       CIBW_FREE_THREADED_SUPPORT: true
       CIBW_BUILD: cp313t-${{ matrix.buildplat }}
-          # TODO: remove along with installing build deps in
-          # cibw_before_build.sh when a released cython can build numpy
+      # TODO:
+      # remove when a released cython can build free-threaded extensions
       CIBW_BUILD_FRONTEND: 'pip; args: --no-build-isolation'
 ```
 
 As above, replace the ellipses with a `cibuildwheel` version.
 
-If your project depends on Cython, you will need to install a Cython nightly
-wheel in the build, as the newest stable release of Cython cannot generate code
-that will compile under the free-threaded build. You likely do not need to
-disable `pip`'s build isolation if your project does not depend on Cython.
+If for some reason disabling build isolation is unworkable, you can also tell
+pip about the nightly wheel index and it will use it in an isolated build. To
+do this, set:
 
-You can install nightly wheels for Cython and NumPy using the following
-install command:
-
-```bash
-pip install -i https://pypi.anaconda.org/scientific-python-nightly-wheels/simple cython numpy
+```yaml
+CIBW_BUILD_FRONTEND: 'pip; args: --pre --extra-index-url "https://pypi.anaconda.org/scientific-python-nightly-wheels/simple"'
 ```
 
+Many projects use `build` instead of `pip` for the build frontend. See [the
+cibuildwheel](https://cibuildwheel.pypa.io/en/stable/options/#build-frontend)
+docs for more information about how to pass arguments to `build` and `pip`. See
+[this
+comment](https://github.com/pypa/build/issues/651#issuecomment-2243025713) on
+the `build` issue tracker if you need to use `build` and cannot disable build
+isolation.
+
 Note that nightly wheels may not be available on all platforms yet. Windows
 wheels, in particular, are not currently available for NumPy or projects that
 depend on NumPy (e.g., SciPy).
@@ -64,5 +82,5 @@ You will also likely need to manually pass `-Xgil=0` or set `PYTHON_GIL=0` in
 your shell environment while running tests to ensure the GIL is actually
 disabled during tests, at least until you can register that your extension
 modules support disabling the GIL via `Py_mod_gil` and all of your runtime test
-dependencies do the same. It is not currently possible to mark that a Cython
-module supports running without the GIL.
+dependencies do the same. See [the porting guide](porting.md) for more
+information about declaring support for free-threaded python in your extension.

docs/porting.md

@@ -148,12 +148,8 @@ after importing a module that does not support the GIL.
             ```
 
     In CI, you will need to ensure a nightly cython is installed for
-    free-threaded builds and disable build isolation by passing
-    `--no-build-isolation` to `pip` at build time. If you
-    use `cibuildwheel` to produce wheels, you can conditionally set
-    `CIBW_BUILD_FRONTEND` to `build; args: --no-build-isolation` for free-threaded
-    builds. If your project normally uses `pip` to build wheels, the variable
-    should be set to `pip; args --no-build-isolation`.
+    free-threaded builds. See [the docs on setting up CI](ci.md) for advice on
+    how to build projects that depend on Cython.
 
 === "f2py"
     Starting with NumPy 2.1.0 (only available via the nightly wheels or the