docs: drop double install and add a few projects (#520)

* docs: project update

* docs: pyproject.toml mention

* Apply suggestions from code review

Co-authored-by: Joe Rickerby <joerick@mac.com>

* docs: one more change from @joerick, dropped double install example

Co-authored-by: Joe Rickerby <joerick@mac.com>

docs/data/projects.yml

@@ -229,3 +229,34 @@
   ci: [travisci]
   os: [windows, apple, linux]
   notes: Dependency injection framework for Python, uses Windows TravisCI
+
+- name: numexpr
+  gh: pydata/numexpr
+  ci: [github, travisci]
+  os: [windows, apple, linux]
+
+- name: PyTables
+  gh: PyTables/PyTables
+  ci: [github]
+  os: [windows, apple, linux]
+
+- name: dd-trace-py
+  gh: DataDog/dd-trace-py
+  ci: [github]
+  os: [windows, apple, linux]
+  notes: Uses custom alternate arch emulation on GitHub
+
+- name: Tokenizer
+  gh: OpenNMT/Tokenizer
+  ci: [github, travisci]
+  os: [apple, linux]
+
+- name: matrixprofile
+  gh: matrix-profile-foundation/matrixprofile
+  ci: [travisci]
+  os: [windows, apple, linux]
+
+- name: cyvcf2
+  gh: brentp/cyvcf2
+  ci: [github]
+  os: [apple, linux]

docs/options.md

@@ -243,7 +243,7 @@ CIBW_BEFORE_ALL_LINUX: yum install -y libffi-dev
 
 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.
+If dependencies are required to build your wheel (for example if you include a header from a Python module), instead of using this command, we recommend adding requirements to a pyproject.toml file. This is reproducible, and users who do not get your wheels (such as Alpine or ClearLinux users) will still benefit.
 
 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. The placeholder `{package}` can be used here; it will be replaced by the path to the package being built by `cibuildwheel`.
 
@@ -254,22 +254,47 @@ Platform-specific variants also available:<br/>
 
 #### Examples
 ```yaml
-# install your project and dependencies before building
-CIBW_BEFORE_BUILD: pip install .
-
-# install something required for the build
+# install something required for the build (you might want to use pyproject.toml instead)
 CIBW_BEFORE_BUILD: pip install pybind11
 
 # chain commands using &&
-CIBW_BEFORE_BUILD: yum install -y libffi-dev && pip install .
+CIBW_BEFORE_BUILD_LINUX: yum install -y libffi-dev && make clean
 
 # run a script that's inside your project
 CIBW_BEFORE_BUILD: bash scripts/prepare_for_build.sh
 
 # if cibuildwheel is called with a package_dir argument, it's available as {package}
-CIBW_BEFORE_BUILD: "{package}/bin/prepare_for_build.sh"
+CIBW_BEFORE_BUILD: "{package}/script/prepare_for_build.sh"
 ```
 
+!!! note
+    If you need dependencies installed for the build, we recommend using pyproject.toml. This is an example pyproject.toml file:
+
+    ```toml
+    [build-system]
+    requires = [
+        "setuptools>=42",
+        "wheel",
+        "Cython",
+        "numpy==1.11.3; python_version<='3.6'",
+        "numpy==1.14.5; python_version=='3.7'",
+        "numpy==1.17.3; python_version=='3.8'",
+        "numpy==1.19.4; python_version>='3.9'",
+    ]
+
+    build-backend = "setuptools.build_meta"
+    ```
+
+    This [PEP 517][]/[PEP 518][] style build allows you to completely control the
+    build environment in cibuildwheel, [PyPA-build][], and pip, doesn't force
+    downstream users to install anything they don't need, and lets you do more
+    complex pinning (Cython, for example, requires a wheel to be built with an
+    equal or earlier version of NumPy; pinning in this way is the only way to
+    ensure your module works on all available NumPy versions).
+
+    [PyPA-build]: https://pypa-build.readthedocs.io/en/latest/
+    [PEP 517]: https://www.python.org/dev/peps/pep-0517/
+    [PEP 518]: https://www.python.org/dev/peps/pep-0517/
 
 ### `CIBW_REPAIR_WHEEL_COMMAND` {: #repair-wheel-command}
 > Execute a shell command to repair each (non-pure Python) built wheel