From ad66e7cc6c11621646bf147fda5cc6bac9371476 Mon Sep 17 00:00:00 2001
From: Joe Rickerby <joerick@mac.com>
Date: Tue, 22 Jun 2021 20:02:24 +0100
Subject: [PATCH] More progress on Setup docs

---
 docs/extra.css | 11 ++++++++---
 docs/setup.md  | 50 ++++++++++++++++++++++++++++++++++++++++++++------
 2 files changed, 52 insertions(+), 9 deletions(-)

diff --git a/docs/extra.css b/docs/extra.css
index 99659ef2..6f6c8284 100644
--- a/docs/extra.css
+++ b/docs/extra.css
@@ -10,6 +10,14 @@ p {
     line-height: 26px;
 }
 
+pre {
+  margin: 1em 0;
+}
+
+pre:first-child {
+  margin-top: 0;
+}
+
 code {
     font-size: 85%;
     background-color: rgba(27,31,35,.05);
@@ -217,6 +225,3 @@ h1, h2, h3, h4, h5, h6 {
   padding-right: 0;
   margin-bottom: 0.5em;
 }
-.tabs.examples pre:first-child {
-  margin-top: 0;
-}
diff --git a/docs/setup.md b/docs/setup.md
index 33cd24ed..efe9dc71 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -8,8 +8,6 @@ Before starting to configure cibuildwheel, it's useful to try to build a wheel
 on your local machine. It's much easier to debug problems on your machine than
 inside a CI system!
 
-## Invoking a build
-
 Start with a clean checkout of your project, inside a new clean virtual
 environment. Make sure your `pip` is up to date, and then invoke:
 
@@ -17,8 +15,8 @@ environment. Make sure your `pip` is up to date, and then invoke:
 pip wheel -w wheelhouse .
 ```
 
-If your build completes without a problem, congratulations! You can move on to
-the next step. Otherwise, you might have one of the following issues:
+If your build completes without a problem, you're in good shape! You can move on to
+the next step. Otherwise, you might have one of the following issues.
 
 ### Missing build dependencies
 
@@ -97,9 +95,49 @@ but otherwise, make a note of these for inclusion in the cibuildwheel option
 
 # Run cibuildwheel locally
 
-`cibuildwheel --platform linux`
+If you've got [Docker](https://www.docker.com/products/docker-desktop)
+installed on your development machine, you can run a Linux build without even
+touching CI.
 
-TODO
+!!! tip
+    Even Windows can run Linux containers these days, but there are a few
+    hoops to jump through. Check [this
+    document](https://docs.microsoft.com/en-us/virtualization/windowscontainers/quick-start/quick-start-windows-10-linux)
+    for more info.
+
+This is convenient as it's quicker to iterate, and because the builds are
+happening in manylinux Docker containers, they're perfectly reproducable.
+
+Install cibuildwheel and run a build like this:
+
+```sh
+pip install cibuildwheel
+cibuildwheel --platform linux
+```
+
+You should see the builds taking place. You can experiment with options by exporting environment variables, for example:
+
+!!! tab "POSIX shell (Linux/macOS)"
+
+    ```sh
+    # build only CPython 3.9
+    export CIBW_BUILD='cp39-*'
+    # run a command to set up the build system
+    export CIBW_BEFORE_ALL='apt install libpng-dev'
+
+    cibuildwheel --platform linux
+    ```
+
+!!! tab "CMD (Windows)"
+
+    ```
+    # build only CPython 3.9
+    set CIBW_BUILD='cp39-*'
+    # run a command to set up the build system
+    set CIBW_BEFORE_ALL='apt install libpng-dev'
+
+    cibuildwheel --platform linux
+    ```
 
 # Configure a CI service