Merge pull request #202 from zacharyburnett/docs/cibw_lib_install_conf

add docs explaining how to install libraries within build environment

Author: Cadair

docs/source/publish.rst

@@ -111,6 +111,36 @@ Packages needed to build the source distribution for testing. Must be a
 string of space-separated apt packages. Default is install nothing
 extra.
 
+.. warning::
+  These libraries are only installed on the host Linux machine.
+  To install libraries or packages within the build environment, alter the
+  ``cibuildwheel`` configuration to add an install command before the build,
+  such as adding an entry to the ``tool.cibuildwheel`` table in ``pyproject.toml``:
+
+  .. code:: toml
+
+    [tool.cibuildwheel.linux]
+    before-build = "apt install libfftw3-dev"
+
+    [tool.cibuildwheel.macos]
+    before-build = "brew install fftw"
+
+  or by [setting a ``CIBW_BEFORE_BUILD_*`` environment variable](https://cibuildwheel.pypa.io/en/stable/options/#before-build):
+
+  .. code:: yaml
+
+    jobs:
+      build:
+        uses: OpenAstronomy/github-actions-workflows/.github/workflows/publish.yml@v1
+        with:
+          env: |
+            CIBW_BEFORE_BUILD_LINUX: apt install libfftw3-dev
+            CIBW_BEFORE_BUILD_MACOS: brew install fftw
+            FFTW_DIR: /opt/homebrew/opt/fftw/lib/
+          targets: |
+            - cp3*-manylinux_x86_64
+            - cp3*-macosx_x86_64
+
 upload_to_pypi
 ^^^^^^^^^^^^^^