From 05ddfb03842bd1e58804bec912796e0f0da03db9 Mon Sep 17 00:00:00 2001
From: "Kevin R. Thornton" <krthornt@uci.edu>
Date: Mon, 8 Apr 2024 15:40:17 -0700
Subject: [PATCH] update docs about building wheels

---
 doc/pages/deploymenttools.md | 36 ++++++++++++++++++++++++++++++++++--
 1 file changed, 34 insertions(+), 2 deletions(-)

diff --git a/doc/pages/deploymenttools.md b/doc/pages/deploymenttools.md
index 26155ead7..4bc903bdb 100644
--- a/doc/pages/deploymenttools.md
+++ b/doc/pages/deploymenttools.md
@@ -158,10 +158,42 @@ If you have a script `$HOME/tmp/foo.py`, you can run it via:
 docker run --rm -v $HOME/tmp:/app IMAGE_NAME /bin/bash -c ". /venv/bin/activate; python /app/foo.py"
 ```
 
-## Linux wheel building
+## Wheel building
+
+### Using `build`
+
+The simplest method is to use `build` to build a wheel for your local system:
+
+```{sh}
+python -m pip install build
+python -m build -w .
+```
+
+This approach requires that rust and the GNU Scientific Library (GSL) are installed on your system.
+
+### Using `cibuildwheel`
+
+```{sh}
+python -m pip install cibuildwheel
+python -m cibuildwheel 
+```
+
+This will build wheels for the Python versions declared in `pyproject.toml` in the root
+of the `fwdpy11` source repo.
+We use this method to automatically generate wheels for each release.
+
+On Linux, the work is done in a Docker container.
+Therefore, your system must be configured to allow your user to use `docker`.
+(`podman` may also be used via `podman-docker`.)
+
+On macos, you will need to have the GSL and rust installed using whatever method you prefer,
+so long as the installs are visible to the `fwdpy11` build system.
+
+
+### Alternate method for Linux
 
 The directory `deployment/linux_wheels` defines a `Docker` work flow to build binary wheels on Linux.
-These scripts are what we use to build wheels for each release.
+These scripts were used to build wheels for each release but were recently replaced with `cibuildwheel` (see above).
 They may also be used to make wheels for development versions on a local machine.
 
 From the `root` of the `fwdpy11` repository.