Rework the setup page to include information about local builds before going to CI

docs/extra.css

@@ -22,6 +22,7 @@ code {
 
 code, pre, tt {
     font-family: SFMono-Regular, Consolas, Liberation Mono, Menlo, monospace;
+    line-height: 1.4;
 }
 
 pre code, pre code.hljs {

docs/setup.md

@@ -2,7 +2,108 @@
 title: 'Setup'
 ---
 
-# GitHub Actions [linux/mac/windows] {: #github-actions}
+# Build your wheel locally
+
+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:
+
+```shell
+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:
+
+### Missing build dependencies
+
+If your build needs Python dependencies, you can resolve this by adding
+package names to the
+[`build-system.requires`](https://www.python.org/dev/peps/pep-0518/#build-system-table)
+section of your pyproject.toml. For example, if your project requires Cython
+to build, your pyproject.toml might include a section like this:
+
+```toml
+[build-system]
+requires = [
+    "setuptools>=42",
+    "wheel",
+    "Cython",
+]
+
+build-backend = "setuptools.build_meta"
+```
+
+If you have other dependencies, you should make a note of these, you'll be
+able to install them using the cibuildwheel options [`CIBW_BEFORE_BUILD`](options.md#before-build) or
+[`CIBW_BEFORE_ALL`](options.md#before-all).
+
+### Actions you need to perform before building
+
+You might need to run some other commands before building, like running a
+script that performs codegen or downloading some data that's not stored in
+your source tree. There are a couple ways to deal with this:
+
+-   Incorporate this into your build process, by adding it to your package's
+    `setup.py`. You can add extra build steps using a structure like this:
+
+    ```python
+    import subprocess
+    import setuptools
+    import setuptools.command.build_py
+
+
+    class BuildPyCommand(setuptools.command.build_py.build_py):
+      """Custom build command."""
+
+      def run(self):
+        # your custom build steps here
+        # e.g.
+        #   subprocess.run(['python', 'scripts/my_custom_script.py'], check=True)
+        setuptools.command.build_py.build_py.run(self)
+
+
+    setuptools.setup(
+        cmdclass={
+            'build_py': BuildPyCommand,
+        },
+        # Usual setup() args.
+        # ...
+    )
+    ```
+
+    This method is usually preferred because in addition to adding being
+    included in the wheel build process, it will help users building from
+    source tarballs as well.
+
+-   Alternatively, you can instruct cibuildwheel to run commands before
+    building your wheel. Take a look at the cibuildwheel options
+    [`CIBW_BEFORE_BUILD`](options.md#before-build) or
+    [`CIBW_BEFORE_ALL`](options.md#before-all).
+
+### Environment variables
+
+Your wheel build might need some environment variables to be set. Consider
+incorporating these into setup.py to allow source tarballs to build (for
+example, using [`extra_compile_args` or
+`extra_link_args`](https://docs.python.org/3/distutils/setupscript.html#other-options)),
+but otherwise, make a note of these for inclusion in the cibuildwheel option
+[`CIBW_ENVIRONMENT`](options.md#environment).
+
+# Run cibuildwheel locally
+
+`cibuildwheel --platform linux`
+
+TODO
+
+# Configure a CI service
+
+## GitHub Actions [linux/mac/windows] {: #github-actions}
 
 To build Linux, Mac, and Windows wheels using GitHub Actions, create a `.github/workflows/build_wheels.yml` file in your repo.
 
@@ -99,7 +200,7 @@ For more info on this file, check out the [docs](https://help.github.com/en/acti
 [`examples/github-deploy.yml`](https://github.com/pypa/cibuildwheel/blob/main/examples/github-deploy.yml) extends this minimal example with a demonstration of how to automatically upload the built wheels to PyPI.
 
 
-# Azure Pipelines [linux/mac/windows] {: #azure-pipelines}
+## Azure Pipelines [linux/mac/windows] {: #azure-pipelines}
 
 To build Linux, Mac, and Windows wheels on Azure Pipelines, create a `azure-pipelines.yml` file in your repo.
 
@@ -113,7 +214,7 @@ Commit this file, enable building of your repo on Azure Pipelines, and push.
 
 Wheels will be stored for you and available through the Pipelines interface. For more info on this file, check out the [docs](https://docs.microsoft.com/en-us/azure/devops/pipelines/yaml-schema).
 
-# Travis CI [linux/windows] {: #travis-ci}
+## Travis CI [linux/windows] {: #travis-ci}
 
 To build Linux and Windows wheels on Travis CI, create a `.travis.yml` file in your repo.
 
@@ -129,7 +230,7 @@ Then setup a deployment method by following the [Travis CI deployment docs](http
 
 [`examples/travis-ci-deploy.yml`](https://github.com/pypa/cibuildwheel/blob/main/examples/travis-ci-deploy.yml) extends this minimal example with a demonstration of how to automatically upload the built wheels to PyPI.
 
-# AppVeyor [linux/mac/windows] {: #appveyor}
+## AppVeyor [linux/mac/windows] {: #appveyor}
 
 To build Linux, Mac, and Windows wheels on AppVeyor, create an `appveyor.yml` file in your repo.
 
@@ -145,7 +246,7 @@ AppVeyor will store the built wheels for you - you can access them from the proj
 
 For more info on this config file, check out the [docs](https://www.appveyor.com/docs/).
 
-# CircleCI [linux/mac] {: #circleci}
+## CircleCI [linux/mac] {: #circleci}
 
 To build Linux and Mac wheels on CircleCI, create a `.circleci/config.yml` file in your repo,
 
@@ -162,7 +263,7 @@ Commit this file, enable building of your repo on CircleCI, and push.
 
 CircleCI will store the built wheels for you - you can access them from the project console. Check out the CircleCI [docs](https://circleci.com/docs/2.0/configuration-reference/#section=configuration) for more info on this config file.
 
-# Gitlab CI [linux] {: #gitlab-ci}
+## Gitlab CI [linux] {: #gitlab-ci}
 
 To build Linux wheels on Gitlab CI, create a `.gitlab-ci.yml` file in your repo,
 
@@ -178,9 +279,13 @@ Gitlab will store the built wheels for you - you can access them from the Pipeli
 
 > ⚠️ Got an error? Check the [FAQ](faq.md).
 
+# Further setup
+
+Once you've got the wheel building successfully, you might want to set up [testing](options.md#test-command) or [automatic releases to PyPI](deliver-to-pypi.md#automatic-method).
+
 <script>
   document.addEventListener('DOMContentLoaded', function() {
-    $('.toctree-l2 a, .rst-content h1').each(function(i, el) {
+    $('a.toctree-l3, .rst-content h2').each(function(i, el) {
       var text = $(el).text()
       var match = text.match(/(.*) \[([a-z/]+)\]/);