diff --git a/README.md b/README.md
index cec3816e..c4c93c99 100644
--- a/README.md
+++ b/README.md
@@ -40,194 +40,6 @@ Usage
`cibuildwheel` is not intended to run on your development machine. It will try to install packages globally; this is no good. Travis CI, CircleCI, and AppVeyor run their builds in isolated environments, so are ideal for this kind of script.
-### Minimal setup
-
-
- Azure Pipelines
- 
- 
- 
-
-
-- Using Azure pipelines, you can build all three platforms on the same service. Create a `azure-pipelines.yml` file in your repo.
-
-**azure-pipelines.yml**
-```yaml
-jobs:
-- job: linux
- pool: {vmImage: 'Ubuntu-16.04'}
- steps:
- - task: UsePythonVersion@0
- - bash: |
- python -m pip install --upgrade pip
- pip install cibuildwheel==0.12.0
- cibuildwheel --output-dir wheelhouse .
- - task: PublishBuildArtifacts@1
- inputs: {pathtoPublish: 'wheelhouse'}
-- job: macos
- pool: {vmImage: 'macOS-10.13'}
- steps:
- - task: UsePythonVersion@0
- - bash: |
- python -m pip install --upgrade pip
- pip install cibuildwheel==0.12.0
- cibuildwheel --output-dir wheelhouse .
- - task: PublishBuildArtifacts@1
- inputs: {pathtoPublish: 'wheelhouse'}
-- job: windows
- pool: {vmImage: 'vs2017-win2016'}
- steps:
- - {task: UsePythonVersion@0, inputs: {versionSpec: '2.7', architecture: x86}}
- - {task: UsePythonVersion@0, inputs: {versionSpec: '2.7', architecture: x64}}
- - {task: UsePythonVersion@0, inputs: {versionSpec: '3.5', architecture: x86}}
- - {task: UsePythonVersion@0, inputs: {versionSpec: '3.5', architecture: x64}}
- - {task: UsePythonVersion@0, inputs: {versionSpec: '3.6', architecture: x86}}
- - {task: UsePythonVersion@0, inputs: {versionSpec: '3.6', architecture: x64}}
- - {task: UsePythonVersion@0, inputs: {versionSpec: '3.7', architecture: x86}}
- - {task: UsePythonVersion@0, inputs: {versionSpec: '3.7', architecture: x64}}
- - script: choco install vcpython27 -f -y
- displayName: Install Visual C++ for Python 2.7
- - bash: |
- python -m pip install --upgrade pip
- pip install cibuildwheel==0.12.0
- cibuildwheel --output-dir wheelhouse .
- - task: PublishBuildArtifacts@1
- inputs: {pathtoPublish: 'wheelhouse'}
-```
-
-
-
-
- Travis CI
-
-
-
-
-- To build Linux and Mac wheels on Travis CI, create a `.travis.yml` file in your repo.
-
- ```
- language: python
-
- matrix:
- include:
- - sudo: required
- services:
- - docker
- env: PIP=pip
- - os: osx
- language: generic
- env: PIP=pip2
-
- script:
- - $PIP install cibuildwheel==0.12.0
- - cibuildwheel --output-dir wheelhouse
- ```
-
- Then setup a deployment method by following the [Travis CI deployment docs](https://docs.travis-ci.com/user/deployment/), or see [Delivering to PyPI](#delivering-to-pypi) below.
-
-
-
-
- CircleCI
-
-
-
-
-- To build Linux and Mac wheels on CircleCI, create a `.circleci/config.yml` file in your repo,
-
- ```
- version: 2
-
- jobs:
- linux-wheels:
- working_directory: ~/linux-wheels
- docker:
- - image: circleci/python:3.6
- steps:
- - checkout
- - setup_remote_docker
- - run:
- name: Build the Linux wheels.
- command: |
- pip install --user cibuildwheel
- cibuildwheel --output-dir wheelhouse
- - store_artifacts:
- path: wheelhouse/
-
- osx-wheels:
- working_directory: ~/osx-wheels
- macos:
- xcode: "10.0.0"
- steps:
- - checkout
- - run:
- name: Build the OS X wheels.
- command: |
- pip install --user cibuildwheel
- cibuildwheel --output-dir wheelhouse
- - store_artifacts:
- path: wheelhouse/
-
- workflows:
- version: 2
- all-tests:
- jobs:
- - linux-wheels
- - osx-wheels
- ```
-
- Note: CircleCI doesn't enable free macOS containers for open source by default, but you can ask for access. See [here](https://circleci.com/docs/2.0/oss/#overview) for more information.
-
- CircleCI will store the built wheels for you - you can access them from the project console.
-
-
-
-
-
- AppVeyor
-
-
-
-- To build Windows wheels on AppVeyor, create an `appveyor.yml` file in your repo.
-
- ```
- build_script:
- - pip install cibuildwheel==0.12.0
- - cibuildwheel --output-dir wheelhouse
- artifacts:
- - path: "wheelhouse\\*.whl"
- name: Wheels
- ```
-
- AppVeyor will store the built wheels for you - you can access them from the project console. Alternatively, you may want to store them in the same place as the Travis CI build. See [AppVeyor deployment docs](https://www.appveyor.com/docs/deployment/) for more info, or see [Delivering to PyPI](#delivering-to-pypi) below.
-
-
-
-- Commit those files, enable building of your repo on Travis CI and AppVeyor, and push.
-
-All being well, you should get wheels delivered to you in a few minutes.
-
-> ⚠️ Got an error? Check the [checklist](#it-didnt-work) below.
-
-### Configuration overview
-
-`cibuildwheel` allows for easy customization of the various phases of the build process demonstrated above:
-
-| | Option | |
-|---|---|---|
-| **Target wheels** | `CIBW_PLATFORM` | Override the auto-detected target platform |
-| | `CIBW_BUILD` | Build only certain Python versions |
-| | `CIBW_SKIP` | Skip certain Python versions |
-| **Build parameters** | `CIBW_BUILD_VERBOSITY` | Increase or decrease the output of `pip wheel` |
-| **Build environment** | `CIBW_ENVIRONMENT` | Set environment variables needed during the build |
-| | `CIBW_BEFORE_BUILD` | Execute a shell command preparing each wheel's build |
-| | `CIBW_MANYLINUX1_X86_64_IMAGE` | Specify an alternative manylinx1 x86_64 docker image |
-| | `CIBW_MANYLINUX1_I686_IMAGE` | Specify an alternative manylinux1 i686 docker image |
-| **Tests** | `CIBW_TEST_COMMAND` | Execute a shell command to test all built wheels |
-| | `CIBW_TEST_REQUIRES` | Install Python dependencies before running the tests |
-| | `CIBW_TEST_EXTRAS` | Install Python dependencies before running the tests using ``extras_require``|
-
-A more detailed description of the options, the allowed values, and some examples can be found in the [Options](#options) section.
### Linux builds on Docker
@@ -269,170 +81,6 @@ optional arguments:
```
-Most of the config is via environment variables. These go into `.travis.yml`, `appveyor.yml`, and `.circleci/config.yml` nicely.
-
-***
-
-| Environment variable: `CIBW_PLATFORM` | Command line argument: `--platform`
-| --- | ---
-
-Options: `auto` `linux` `macos` `windows`
-
-Default: `auto`
-
-`auto` will auto-detect platform using environment variables, such as `TRAVIS_OS_NAME`/`APPVEYOR`/`CIRCLECI`.
-
-For `linux` you need Docker running, on Mac or Linux. For `macos`, you need a Mac machine, and note that this script is going to automatically install MacPython on your system, so don't run on your development machine. For `windows`, you need to run in Windows, and it will build and test for all versions of Python at `C:\PythonXX[-x64]`.
-
-***
-
-| Environment variables: `CIBW_BUILD` and `CIBW_SKIP`
-| ---
-
-Optional.
-
-Space-separated list of builds to build and skip. Each build has an identifier like `cp27-manylinux1_x86_64` or `cp34-macosx_10_6_intel` - you can list specific ones to build and `cibuildwheel` will only build those, and/or list ones to skip and `cibuildwheel` won't try to build them.
-
-When both options are specified, both conditions are applied and only builds with a tag that matches `CIBW_BUILD` and does not match `CIBW_SKIP` will be built.
-
-The format is `python_tag-platform_tag`. The tags are as defined in [PEP 0425](https://www.python.org/dev/peps/pep-0425/#details).
-
-Python tags look like `cp27` `cp34` `cp35` `cp36` `cp37`
-
-Platform tags look like `macosx_10_6_intel` `manylinux1_x86_64` `manylinux1_i686` `win32` `win_amd64`
-
-You can also use shell-style globbing syntax (as per `fnmatch`)
-
-Examples:
-- Only build on Python 3.6: `CIBW_BUILD`:`cp36-*`
-- Skip building on Python 2.7 on the Mac: `CIBW_SKIP`:`cp27-macosx_10_6_intel`
-- Skip building on Python 2.7 on all platforms: `CIBW_SKIP`:`cp27-*`
-- Skip Python 2.7 on Windows: `CIBW_SKIP`:`cp27-win*`
-- Skip Python 2.7 on 32-bit Windows: `CIBW_SKIP`:`cp27-win32`
-- Skip Python 3.4 and Python 3.5: `CIBW_SKIP`:`cp34-* cp35-*`
-- Skip Python 3.6 on Linux: `CIBW_SKIP`:`cp36-manylinux*`
-- Only build on Python 3 and skip 32-bit builds: `CIBW_BUILD`:`cp3?-*` and `CIBW_SKIP`:`*-win32 *-manylinux1_i686`
-
-***
-
-| Environment variable: `CIBW_BUILD_VERBOSITY`
-| ---
-
-Optional.
-
-An number from 1 to 3 to increase the level of verbosity (corresponding to invoking pip with `-v`, `-vv`, and `-vvv`), between -1 and -3 (`-q`, `-qq`, and `-qqq`), or just 0 (default verbosity). These flags are useful while debugging a build when the output of the actual build invoked by `pip wheel` is required.
-
-Platform-specific variants also available:
-`CIBW_BUILD_VERBOSITY_MACOS` | `CIBW_BUILD_VERBOSITY_WINDOWS` | `CIBW_BUILD_VERBOSITY_LINUX`
-
-***
-
-| Environment variable: `CIBW_ENVIRONMENT`
-| ---
-
-Optional.
-
-A space-separated list of environment variables to set during the build. Bash syntax should be used (even on Windows!).
-
-You must set this variable to pass variables to Linux builds (since they execute in a Docker container). It also works for the other platforms.
-
-You can use `$PATH` syntax to insert other variables, or the `$(pwd)` syntax to insert the output of other shell commands.
-
-Example: `CFLAGS="-g -Wall" CXXFLAGS="-Wall"`
-Example: `PATH=$PATH:/usr/local/bin`
-Example: `BUILD_TIME="$(date)"`
-Example: `PIP_EXTRA_INDEX_URL="https://pypi.myorg.com/simple"`
-
-Platform-specific variants also available:
-`CIBW_ENVIRONMENT_MACOS` | `CIBW_ENVIRONMENT_WINDOWS` | `CIBW_ENVIRONMENT_LINUX`
-
-In addition to the above, `cibuildwheel` always defines the environment variable `CIBUILDWHEEL=1`. This can be useful for [building wheels with optional extensions](https://github.com/joerick/cibuildwheel/wiki/Building-packages-with-optional-C-extensions).
-
-***
-
-| Environment variable: `CIBW_BEFORE_BUILD`
-| ---
-
-Optional.
-
-A shell command to run before building the wheel. This option allows you to run a command in **each** Python environment before the `pip wheel` command. This is useful if you need to set up some dependency so it's available during the build.
-
-If dependencies are required to build your wheel (for example if you include a header from a Python module), set this to `pip install .`, and the dependencies will be installed automatically by pip. However, this means your package will be built twice - if your package takes a long time to build, you might wish to manually list the dependencies here instead.
-
-The active Python binary can be accessed using `python`, and pip with `pip`; `cibuildwheel` makes sure the right version of Python and pip will be executed. `{project}` can be used as a placeholder for the absolute path to the project's root.
-
-Example: `pip install .`
-Example: `pip install pybind11`
-Example: `yum install -y libffi-dev && pip install .`
-
-Platform-specific variants also available:
- `CIBW_BEFORE_BUILD_MACOS` | `CIBW_BEFORE_BUILD_WINDOWS` | `CIBW_BEFORE_BUILD_LINUX`
-
-***
-
-| Environment variables: `CIBW_MANYLINUX1_X86_64_IMAGE` and `CIBW_MANYLINUX1_I686_IMAGE`
-| ---
-
-Optional.
-
-An alternative docker image to be used for building [`manylinux1`](https://github.com/pypa/manylinux) wheels. `cibuildwheel` will then pull these instead of the official images, [`quay.io/pypa/manylinux1_x86_64`](https://quay.io/pypa/manylinux1_i686) and [`quay.io/pypa/manylinux1_i686`](https://quay.io/pypa/manylinux1_i686).
-
-Beware to specify a valid docker image that can be used the same as the official, default docker images: all necessary Python and pip versions need to be present in `/opt/python/`, and the `auditwheel` tool needs to be present for `cibuildwheel` to work. Apart from that, the architecture and relevant shared system libraries need to be manylinux1-compatible in order to produce valid `manylinux1` wheels (see https://github.com/pypa/manylinux and [PEP 513](https://www.python.org/dev/peps/pep-0513/) for more details).
-
-Example: `dockcross/manylinux-x64`
-Example: `dockcross/manylinux-x86`
-
-***
-
-| Environment variable: `CIBW_TEST_COMMAND`
-| ---
-
-Optional.
-
-Shell command to run tests after the build. The wheel will be installed automatically and available for import from the tests. `{project}` can be used as a placeholder for the absolute path to the project's root and will be replaced by `cibuildwheel`.
-
-On Linux and Mac, the command runs in a shell, so you can write things like `cmd1 && cmd2`.
-
-Example: `nosetests {project}/tests`
-
-Platform-specific variants also available:
-`CIBW_TEST_COMMAND_MACOS` | `CIBW_TEST_COMMAND_WINDOWS` | `CIBW_TEST_COMMAND_LINUX`
-
-***
-
-| Environment variable: `CIBW_TEST_REQUIRES`
-| ---
-
-Optional.
-
-Space-separated list of dependencies required for running the tests.
-
-Example: `pytest`
-Example: `nose==1.3.7 moto==0.4.31`
-
-Platform-specific variants also available:
-`CIBW_TEST_REQUIRES_MACOS` | `CIBW_TEST_REQUIRES_WINDOWS` | `CIBW_TEST_REQUIRES_LINUX`
-
-***
-
-| Environment variable: `CIBW_TEST_EXTRAS`
-| ---
-
-Optional.
-
-Comma-separated list of
-[extras_require](https://setuptools.readthedocs.io/en/latest/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies)
-options that should be included when installing the wheel prior to running the
-tests. This can be used to avoid having to redefine test dependencies in
-`CIBW_TEST_REQUIRES` if they are already defined in `setup.py` or
-`setup.cfg`.
-
-Example: `test,qt` (will cause the wheel to be installed with `pip install [test,qt]`)
-
-
-Platform-specific variants also available:
-`CIBW_TEST_EXTRAS_MACOS` | `CIBW_TEST_EXTRAS_WINDOWS` | `CIBW_TEST_EXTRAS_LINUX`
-
### Example YML syntax
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 00000000..01e0d0cd
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,39 @@
+Home
+====
+
+Python wheels are great. Building them across **Mac, Linux, Windows**, on **multiple versions of Python**, is not.
+
+`cibuildwheel` is here to help. `cibuildwheel` runs on your CI server - currently it supports Azure Pipelines, Travis CI, AppVeyor, and CircleCI - and it builds and tests your wheels across all of your platforms.
+
+**`cibuildwheel` is in beta**. It's brand new - I'd love for you to try it and help make it better!
+
+What does it do?
+----------------
+
+| | macOS 10.6+ | manylinux i686 | manylinux x86_64 | Windows 32bit | Windows 64bit |
+|---|---|---|---|---|---|
+| Python 2.7 | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Python 3.4 | ✅ | ✅ | ✅ | ✅* | ✅* |
+| Python 3.5 | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Python 3.6 | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Python 3.7 | ✅ | ✅ | ✅ | ✅ | ✅ |
+
+> \* Not supported on Azure Pipelines
+
+- Builds manylinux, macOS and Windows (32 and 64bit) wheels using Azure Pipelines, Travis CI, AppVeyor, and CircleCI
+- Bundles shared library dependencies on Linux and macOS through [auditwheel](https://github.com/pypa/auditwheel) and [delocate](https://github.com/matthew-brett/delocate)
+- Runs the library test suite against the wheel-installed version of your library
+
+Usage
+-----
+
+`cibuildwheel` currently works **Travis CI** and **CircleCI** to build Linux and Mac wheels, and **AppVeyor** to build Windows wheels. **Azure Pipelines** supports all three.
+
+| | Linux | macOS | Windows |
+|-----------------|-------|-------|---------|
+| Azure Pipelines | ✅ | ✅ | ✅ |
+| Travis CI | ✅ | ✅ | |
+| AppVeyor | | | ✅ |
+| CircleCI | ✅ | ✅ | |
+
+`cibuildwheel` is not intended to run on your development machine. It will try to install packages globally; this is no good. Travis CI, CircleCI, and AppVeyor run their builds in isolated environments, so are ideal for this kind of script.
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
deleted file mode 100644
index 3fe64b17..00000000
--- a/docs/mkdocs.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-site_name: My Docs
-docs_dir: pages
diff --git a/docs/options.md b/docs/options.md
new file mode 100644
index 00000000..6174e1b9
--- /dev/null
+++ b/docs/options.md
@@ -0,0 +1,178 @@
+## Options summary
+
+`cibuildwheel` allows for easy customization of the various phases of the build process demonstrated above:
+
+| | Option | |
+|---|---|---|
+| **Target wheels** | `CIBW_PLATFORM` | Override the auto-detected target platform |
+| | `CIBW_BUILD` | Build only certain Python versions |
+| | `CIBW_SKIP` | Skip certain Python versions |
+| **Build parameters** | `CIBW_BUILD_VERBOSITY` | Increase or decrease the output of `pip wheel` |
+| **Build environment** | `CIBW_ENVIRONMENT` | Set environment variables needed during the build |
+| | `CIBW_BEFORE_BUILD` | Execute a shell command preparing each wheel's build |
+| | `CIBW_MANYLINUX1_X86_64_IMAGE` | Specify an alternative manylinx1 x86_64 docker image |
+| | `CIBW_MANYLINUX1_I686_IMAGE` | Specify an alternative manylinux1 i686 docker image |
+| **Tests** | `CIBW_TEST_COMMAND` | Execute a shell command to test all built wheels |
+| | `CIBW_TEST_REQUIRES` | Install Python dependencies before running the tests |
+| | `CIBW_TEST_EXTRAS` | Install Python dependencies before running the tests using ``extras_require``|
+
+Most of the config is via environment variables. These go into `.travis.yml`, `appveyor.yml`, and `.circleci/config.yml` nicely.
+
+## Build selection
+
+### CIBW_PLATFORM
+
+Options: `auto` `linux` `macos` `windows`
+
+Default: `auto`
+
+`auto` will auto-detect platform using environment variables, such as `TRAVIS_OS_NAME`/`APPVEYOR`/`CIRCLECI`.
+
+For `linux` you need Docker running, on Mac or Linux. For `macos`, you need a Mac machine, and note that this script is going to automatically install MacPython on your system, so don't run on your development machine. For `windows`, you need to run in Windows, and it will build and test for all versions of Python at `C:\PythonXX[-x64]`.
+
+### CIBW_BUILD and CIBW_SKIP
+
+Space-separated list of builds to build and skip. Each build has an identifier like `cp27-manylinux1_x86_64` or `cp34-macosx_10_6_intel` - you can list specific ones to build and `cibuildwheel` will only build those, and/or list ones to skip and `cibuildwheel` won't try to build them.
+
+When both options are specified, both conditions are applied and only builds with a tag that matches `CIBW_BUILD` and does not match `CIBW_SKIP` will be built.
+
+The format is `python_tag-platform_tag`. The tags are as defined in [PEP 0425](https://www.python.org/dev/peps/pep-0425/#details).
+
+Python tags look like `cp27` `cp34` `cp35` `cp36` `cp37`
+
+Platform tags look like `macosx_10_6_intel` `manylinux1_x86_64` `manylinux1_i686` `win32` `win_amd64`
+
+You can also use shell-style globbing syntax (as per `fnmatch`)
+
+Examples:
+
+- Only build on Python 3.6: `CIBW_BUILD=cp36-*`
+- Skip building on Python 2.7 on the Mac: `CIBW_SKIP=cp27-macosx_10_6_intel`
+- Skip building on Python 2.7 on all platforms: `CIBW_SKIP=cp27-*`
+- Skip Python 2.7 on Windows: `CIBW_SKIP=cp27-win*`
+- Skip Python 2.7 on 32-bit Windows: `CIBW_SKIP=cp27-win32`
+- Skip Python 3.4 and Python 3.5: `CIBW_SKIP=cp34-* cp35-*`
+- Skip Python 3.6 on Linux: `CIBW_SKIP=cp36-manylinux*`
+- Only build on Python 3 and skip 32-bit builds: `CIBW_BUILD=cp3?-*` and `CIBW_SKIP=*-win32 *-manylinux1_i686`
+
+## Build environment
+
+### CIBW_ENVIRONMENT
+
+A space-separated list of environment variables to set during the build. Bash syntax should be used (even on Windows!).
+
+You must set this variable to pass variables to Linux builds (since they execute in a Docker container). It also works for the other platforms.
+
+You can use `$PATH` syntax to insert other variables, or the `$(pwd)` syntax to insert the output of other shell commands.
+
+Example: `CFLAGS="-g -Wall" CXXFLAGS="-Wall"`
+Example: `PATH=$PATH:/usr/local/bin`
+Example: `BUILD_TIME="$(date)"`
+Example: `PIP_EXTRA_INDEX_URL="https://pypi.myorg.com/simple"`
+
+Platform-specific variants also available:
+`CIBW_ENVIRONMENT_MACOS` | `CIBW_ENVIRONMENT_WINDOWS` | `CIBW_ENVIRONMENT_LINUX`
+
+In addition to the above, `cibuildwheel` always defines the environment variable `CIBUILDWHEEL=1`. This can be useful for [building wheels with optional extensions](https://github.com/joerick/cibuildwheel/wiki/Building-packages-with-optional-C-extensions).
+
+### CIBW_BEFORE_BUILD
+
+A shell command to run before building the wheel. This option allows you to run a command in **each** Python environment before the `pip wheel` command. This is useful if you need to set up some dependency so it's available during the build.
+
+If dependencies are required to build your wheel (for example if you include a header from a Python module), set this to `pip install .`, and the dependencies will be installed automatically by pip. However, this means your package will be built twice - if your package takes a long time to build, you might wish to manually list the dependencies here instead.
+
+The active Python binary can be accessed using `python`, and pip with `pip`; `cibuildwheel` makes sure the right version of Python and pip will be executed. `{project}` can be used as a placeholder for the absolute path to the project's root.
+
+Example: `pip install .`
+Example: `pip install pybind11`
+Example: `yum install -y libffi-dev && pip install .`
+
+Platform-specific variants also available:
+ `CIBW_BEFORE_BUILD_MACOS` | `CIBW_BEFORE_BUILD_WINDOWS` | `CIBW_BEFORE_BUILD_LINUX`
+
+### CIBW_MANYLINUX1_X86_64_IMAGE and CIBW_MANYLINUX1_I686_IMAGE
+
+An alternative docker image to be used for building [`manylinux1`](https://github.com/pypa/manylinux) wheels. `cibuildwheel` will then pull these instead of the official images, [`quay.io/pypa/manylinux1_x86_64`](https://quay.io/pypa/manylinux1_i686) and [`quay.io/pypa/manylinux1_i686`](https://quay.io/pypa/manylinux1_i686).
+
+Beware to specify a valid docker image that can be used the same as the official, default docker images: all necessary Python and pip versions need to be present in `/opt/python/`, and the `auditwheel` tool needs to be present for `cibuildwheel` to work. Apart from that, the architecture and relevant shared system libraries need to be manylinux1-compatible in order to produce valid `manylinux1` wheels (see https://github.com/pypa/manylinux and [PEP 513](https://www.python.org/dev/peps/pep-0513/) for more details).
+
+Example: `dockcross/manylinux-x64`
+Example: `dockcross/manylinux-x86`
+
+## Testing
+
+### CIBW_TEST_COMMAND
+
+Shell command to run tests after the build. The wheel will be installed automatically and available for import from the tests. `{project}` can be used as a placeholder for the absolute path to the project's root and will be replaced by `cibuildwheel`.
+
+On Linux and Mac, the command runs in a shell, so you can write things like `cmd1 && cmd2`.
+
+Example: `nosetests {project}/tests`
+
+Platform-specific variants also available:
+`CIBW_TEST_COMMAND_MACOS` | `CIBW_TEST_COMMAND_WINDOWS` | `CIBW_TEST_COMMAND_LINUX`
+
+### CIBW_TEST_REQUIRES
+
+Space-separated list of dependencies required for running the tests.
+
+Example: `pytest`
+Example: `nose==1.3.7 moto==0.4.31`
+
+Platform-specific variants also available:
+`CIBW_TEST_REQUIRES_MACOS` | `CIBW_TEST_REQUIRES_WINDOWS` | `CIBW_TEST_REQUIRES_LINUX`
+
+### CIBW_TEST_EXTRAS
+
+Comma-separated list of
+[extras_require](https://setuptools.readthedocs.io/en/latest/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies)
+options that should be included when installing the wheel prior to running the
+tests. This can be used to avoid having to redefine test dependencies in
+`CIBW_TEST_REQUIRES` if they are already defined in `setup.py` or
+`setup.cfg`.
+
+Example: `test,qt` (will cause the wheel to be installed with `pip install [test,qt]`)
+
+
+Platform-specific variants also available:
+`CIBW_TEST_EXTRAS_MACOS` | `CIBW_TEST_EXTRAS_WINDOWS` | `CIBW_TEST_EXTRAS_LINUX`
+
+## Other
+
+### CIBW_BUILD_VERBOSITY
+
+An number from 1 to 3 to increase the level of verbosity (corresponding to invoking pip with `-v`, `-vv`, and `-vvv`), between -1 and -3 (`-q`, `-qq`, and `-qqq`), or just 0 (default verbosity). These flags are useful while debugging a build when the output of the actual build invoked by `pip wheel` is required.
+
+Platform-specific variants also available:
+`CIBW_BUILD_VERBOSITY_MACOS` | `CIBW_BUILD_VERBOSITY_WINDOWS` | `CIBW_BUILD_VERBOSITY_LINUX`
+
+## Command line options
+
+```
+usage: cibuildwheel [-h] [--platform {auto,linux,macos,windows}]
+ [--output-dir OUTPUT_DIR] [--print-build-identifiers]
+ [project_dir]
+
+Build wheels for all the platforms.
+
+positional arguments:
+ project_dir Path to the project that you want wheels for.
+ Default: the current directory.
+
+optional arguments:
+ -h, --help show this help message and exit
+ --platform {auto,linux,macos,windows}
+ Platform to build for. For "linux" you need docker
+ running, on Mac or Linux. For "macos", you need a Mac
+ machine, and note that this script is going to
+ automatically install MacPython on your system, so
+ don't run on your development machine. For "windows",
+ you need to run in Windows, and it will build and test
+ for all versions of Python at C:\PythonXX[-x64].
+ --output-dir OUTPUT_DIR
+ Destination folder for the wheels.
+ --print-build-identifiers
+ Print the build identifiers matched by the current
+ invocation and exit.
+
+```
diff --git a/docs/pages/index.md b/docs/pages/index.md
deleted file mode 100644
index d3880397..00000000
--- a/docs/pages/index.md
+++ /dev/null
@@ -1,17 +0,0 @@
-# Welcome to MkDocs
-
-For full documentation visit [mkdocs.org](https://mkdocs.org).
-
-## Commands
-
-* `mkdocs new [dir-name]` - Create a new project.
-* `mkdocs serve` - Start the live-reloading docs server.
-* `mkdocs build` - Build the documentation site.
-* `mkdocs help` - Print this help message.
-
-## Project layout
-
- mkdocs.yml # The configuration file.
- docs/
- index.md # The documentation homepage.
- ... # Other markdown pages, images and other files.
diff --git a/docs/setup.md b/docs/setup.md
new file mode 100644
index 00000000..5fb1c3ac
--- /dev/null
+++ b/docs/setup.md
@@ -0,0 +1,141 @@
+## Azure Pipelines [linux/mac/windows]
+
+Using Azure pipelines, you can build all three platforms on the same service. Create a `azure-pipelines.yml` file in your repo.
+
+**azure-pipelines.yml**
+```yaml
+jobs:
+- job: linux
+ pool: {vmImage: 'Ubuntu-16.04'}
+ steps:
+ - task: UsePythonVersion@0
+ - bash: |
+ python -m pip install --upgrade pip
+ pip install cibuildwheel==0.12.0
+ cibuildwheel --output-dir wheelhouse .
+ - task: PublishBuildArtifacts@1
+ inputs: {pathtoPublish: 'wheelhouse'}
+- job: macos
+ pool: {vmImage: 'macOS-10.13'}
+ steps:
+ - task: UsePythonVersion@0
+ - bash: |
+ python -m pip install --upgrade pip
+ pip install cibuildwheel==0.12.0
+ cibuildwheel --output-dir wheelhouse .
+ - task: PublishBuildArtifacts@1
+ inputs: {pathtoPublish: 'wheelhouse'}
+- job: windows
+ pool: {vmImage: 'vs2017-win2016'}
+ steps:
+ - {task: UsePythonVersion@0, inputs: {versionSpec: '2.7', architecture: x86}}
+ - {task: UsePythonVersion@0, inputs: {versionSpec: '2.7', architecture: x64}}
+ - {task: UsePythonVersion@0, inputs: {versionSpec: '3.5', architecture: x86}}
+ - {task: UsePythonVersion@0, inputs: {versionSpec: '3.5', architecture: x64}}
+ - {task: UsePythonVersion@0, inputs: {versionSpec: '3.6', architecture: x86}}
+ - {task: UsePythonVersion@0, inputs: {versionSpec: '3.6', architecture: x64}}
+ - {task: UsePythonVersion@0, inputs: {versionSpec: '3.7', architecture: x86}}
+ - {task: UsePythonVersion@0, inputs: {versionSpec: '3.7', architecture: x64}}
+ - script: choco install vcpython27 -f -y
+ displayName: Install Visual C++ for Python 2.7
+ - bash: |
+ python -m pip install --upgrade pip
+ pip install cibuildwheel==0.12.0
+ cibuildwheel --output-dir wheelhouse .
+ - task: PublishBuildArtifacts@1
+ inputs: {pathtoPublish: 'wheelhouse'}
+```
+
+## Travis CI [linux/mac]
+
+To build Linux and Mac wheels on Travis CI, create a `.travis.yml` file in your repo.
+
+```yaml
+language: python
+
+matrix:
+ include:
+ - sudo: required
+ services:
+ - docker
+ env: PIP=pip
+ - os: osx
+ language: generic
+ env: PIP=pip2
+
+script:
+ - $PIP install cibuildwheel==0.12.0
+ - cibuildwheel --output-dir wheelhouse
+```
+
+Then setup a deployment method by following the [Travis CI deployment docs](https://docs.travis-ci.com/user/deployment/), or see [Delivering to PyPI](#delivering-to-pypi) below.
+
+## CircleCI [linux/mac]
+
+To build Linux and Mac wheels on CircleCI, create a `.circleci/config.yml` file in your repo,
+
+```yaml
+version: 2
+
+jobs:
+ linux-wheels:
+ working_directory: ~/linux-wheels
+ docker:
+ - image: circleci/python:3.6
+ steps:
+ - checkout
+ - setup_remote_docker
+ - run:
+ name: Build the Linux wheels.
+ command: |
+ pip install --user cibuildwheel
+ cibuildwheel --output-dir wheelhouse
+ - store_artifacts:
+ path: wheelhouse/
+
+ osx-wheels:
+ working_directory: ~/osx-wheels
+ macos:
+ xcode: "10.0.0"
+ steps:
+ - checkout
+ - run:
+ name: Build the OS X wheels.
+ command: |
+ pip install --user cibuildwheel
+ cibuildwheel --output-dir wheelhouse
+ - store_artifacts:
+ path: wheelhouse/
+
+workflows:
+ version: 2
+ all-tests:
+ jobs:
+ - linux-wheels
+ - osx-wheels
+```
+
+Note: CircleCI doesn't enable free macOS containers for open source by default, but you can ask for access. See [here](https://circleci.com/docs/2.0/oss/#overview) for more information.
+
+CircleCI will store the built wheels for you - you can access them from the project console.
+
+## AppVeyor [windows]
+
+To build Windows wheels on AppVeyor, create an `appveyor.yml` file in your repo.
+
+```yaml
+build_script:
+ - pip install cibuildwheel==0.12.0
+ - cibuildwheel --output-dir wheelhouse
+artifacts:
+ - path: "wheelhouse\\*.whl"
+ name: Wheels
+```
+
+AppVeyor will store the built wheels for you - you can access them from the project console. Alternatively, you may want to store them in the same place as the Travis CI build. See [AppVeyor deployment docs](https://www.appveyor.com/docs/deployment/) for more info, or see [Delivering to PyPI](#delivering-to-pypi) below.
+
+Commit those files, enable building of your repo on Travis CI and AppVeyor, and push.
+
+All being well, you should get wheels delivered to you in a few minutes.
+
+> ⚠️ Got an error? Check the [checklist](#it-didnt-work) below.
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 00000000..5d5bb2fb
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,10 @@
+site_name: cibuildwheel
+docs_dir: docs
+theme: readthedocs
+nav:
+ - Home: index.md
+ - "Setup guide": setup.md
+ - "Options": options.md
+markdown_extensions:
+- codehilite
+- fenced_code
\ No newline at end of file