Merge pull request #162 from davidhewitt/wheel-building-docs

docs: add wheel-building notes

Author: davidhewitt

README.md

@@ -1,7 +1,7 @@
 # Setuptools plugin for Rust extensions
 
-![example workflow](https://github.com/PyO3/setuptools-rust/actions/workflows/ci.yml/badge.svg)
-[![pypi package](https://badge.fury.io/py/setuptools-rust.svg)](https://badge.fury.io/py/setuptools-rust)
+[![github actions](https://github.com/PyO3/setuptools-rust/actions/workflows/ci.yml/badge.svg)](https://github.com/PyO3/setuptools-rust/actions/workflows/ci.yml)
+[![pypi package](https://badge.fury.io/py/setuptools-rust.svg)](https://pypi.org/project/setuptools-rust/)
 [![readthedocs](https://readthedocs.org/projects/pip/badge/)](https://setuptools-rust.readthedocs.io/en/latest/)
 [![code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)
 
@@ -36,41 +36,20 @@ setup(
 For a complete reference of the options supported by the `RustExtension` class, see the
 [API reference](https://setuptools-rust.readthedocs.io/en/latest/reference.html).
 
-### MANIFEST.in
-
-This file is required for building source distributions
-
-```text
-include Cargo.toml
-recursive-include src *
-```
-
 ### pyproject.toml
 
 ```toml
 [build-system]
 requires = ["setuptools", "wheel", "setuptools-rust"]
 ```
 
-### build-wheels.sh
-
-```bash
-#!/bin/bash
-set -ex
-
-curl https://sh.rustup.rs -sSf | sh -s -- --default-toolchain stable -y
-export PATH="$HOME/.cargo/bin:$PATH"
-
-cd /io
+### MANIFEST.in
 
-for PYBIN in /opt/python/cp{35,36,37,38,39}*/bin; do
-    "${PYBIN}/pip" install -U setuptools wheel setuptools-rust
-    "${PYBIN}/python" setup.py bdist_wheel
-done
+This file is required for building source distributions
 
-for whl in dist/*.whl; do
-    auditwheel repair "$whl" -w dist/
-done
+```text
+include Cargo.toml
+recursive-include src *
 ```
 
 ## Usage
@@ -98,47 +77,10 @@ Processing dependencies for hello_rust==1.0
 Finished processing dependencies for hello_rust==1.0
 ```
 
-Or you can use commands like bdist_wheel (after installing wheel).
+Or you can use commands like ``bdist_wheel`` (after installing ``wheel``). See also [the notes in the documentation about building wheels](https://setuptools-rust.readthedocs.io/en/latest/building_wheels.html).
 
 By default, `develop` will create a debug build, while `install` will create a release build.
 
-### Binary wheels on linux
-
-To build binary wheels on linux, you need to use the [manylinux docker container](https://github.com/pypa/manylinux). You also need a `build-wheels.sh` similar to [the one in the example](https://github.com/PyO3/setuptools-rust/blob/main/examples/html-py-ever/build-wheels.sh), which will be run in that container.
-
-First, pull the `manylinux2014` Docker image:
-
-```bash
-docker pull quay.io/pypa/manylinux2014_x86_64
-```
-
-Then use the following command to build wheels for supported Python versions:
-
-```bash
-docker run --rm -v `pwd`:/io quay.io/pypa/manylinux2014_x86_64 bash /io/build-wheels.sh
-```
-
-This will create wheels in the `dist` directory:
-
-```bash
-$ ls dist
-hello_rust-0.1.0-cp35-cp35m-linux_x86_64.whl          hello_rust-0.1.0-cp35-cp35m-manylinux2014_x86_64.whl
-hello_rust-0.1.0-cp36-cp36m-linux_x86_64.whl          hello_rust-0.1.0-cp36-cp36m-manylinux2014_x86_64.whl
-hello_rust-0.1.0-cp37-cp37m-linux_x86_64.whl          hello_rust-0.1.0-cp37-cp37m-manylinux2014_x86_64.whl
-hello_rust-0.1.0-cp38-cp38-linux_x86_64.whl           hello_rust-0.1.0-cp38-cp38-manylinux2014_x86_64.whl
-hello_rust-0.1.0-cp39-cp39-linux_x86_64.whl           hello_rust-0.1.0-cp39-cp39-manylinux2014_x86_64.whl
-```
-
-You can then upload the `manylinux2014` wheels to pypi using [twine](https://github.com/pypa/twine).
-
-It is possible to use any of the `manylinux` docker images: `manylinux1`, `manylinux2010` or `manylinux2014`. (Just replace `manylinux2014` in the above instructions with the alternative version you wish to use.)
-
-### Binary wheels on macOS
-
-For building wheels on macOS it is sufficient to run the `bdist_wheel` command, i.e. `setup.py bdist_wheel`.
-
-To build `universal2` wheels set the `ARCHFLAGS` environment variable to contain both `x86_64` and `arm64`, for example `ARCHFLAGS="-arch x86_64 -arch arm64"`. Wheel-building solutions such as [`cibuildwheel`](https://github.com/joerick/cibuildwheel) set this environment variable automatically.
-
 ## Commands
 
   - `build` - Standard build command will also build all rust extensions.

docs/building_wheels.rst

@@ -0,0 +1,81 @@
+Building wheels
+===============
+
+Because ``setuptools_rust`` is an extension to ``setuptools``, the standard ``setup.py bdist_wheel`` command is used to build wheels which can be uploaded to pypy.
+
+This doc suggests two ways to go about this.
+
+Using ``cibuildwheel``
+----------------------
+
+`cibuildwheel`_ is a tool to build wheels for multiple platforms using Github Actions.
+
+The `rtoml package does this, for example <https://github.com/samuelcolvin/rtoml/blob/143ee0907bba616cbcd5cc58eefe9000fcc2b5f2/.github/workflows/ci.yml#L99-L195>`_.
+
+Building manually
+-----------------
+
+Place a script called ``build-wheels.sh`` with the following contents in your project root (next to the ``setup.py`` file):
+
+.. code-block:: bash
+
+    #!/bin/bash
+    set -ex
+
+    curl https://sh.rustup.rs -sSf | sh -s -- --default-toolchain stable -y
+    export PATH="$HOME/.cargo/bin:$PATH"
+
+    cd /io
+
+    for PYBIN in /opt/python/cp{36,37,38,39}*/bin; do
+        "${PYBIN}/pip" install -U setuptools wheel setuptools-rust
+        "${PYBIN}/python" setup.py bdist_wheel
+    done
+
+    for whl in dist/*.whl; do
+        auditwheel repair "$whl" -w dist/
+    done
+
+This script can be used to produce wheels for multiple Python versions.
+
+Binary wheels on linux
+^^^^^^^^^^^^^^^^^^^^^^
+
+To build binary wheels on linux, you need to use the `manylinux docker container <https://github.com/pypa/manylinux>`_. You also need a ``build-wheels.sh`` similar to `the one in the example <https://github.com/PyO3/setuptools-rust/blob/main/examples/html-py-ever/build-wheels.sh>`_, which will be run in that container.
+
+First, pull the ``manylinux2014`` Docker image:
+
+.. code-block:: bash
+
+    docker pull quay.io/pypa/manylinux2014_x86_64
+
+
+Then use the following command to build wheels for supported Python versions:
+
+.. code-block:: bash
+
+    docker run --rm -v `pwd`:/io quay.io/pypa/manylinux2014_x86_64 bash /io/build-wheels.sh
+
+This will create wheels in the ``dist`` directory:
+
+.. code-block:: bash
+
+    $ ls dist
+    hello_rust-0.1.0-cp36-cp36m-linux_x86_64.whl          hello_rust-0.1.0-cp36-cp36m-manylinux2014_x86_64.whl
+    hello_rust-0.1.0-cp37-cp37m-linux_x86_64.whl          hello_rust-0.1.0-cp37-cp37m-manylinux2014_x86_64.whl
+    hello_rust-0.1.0-cp38-cp38-linux_x86_64.whl           hello_rust-0.1.0-cp38-cp38-manylinux2014_x86_64.whl
+    hello_rust-0.1.0-cp39-cp39-linux_x86_64.whl           hello_rust-0.1.0-cp39-cp39-manylinux2014_x86_64.whl
+
+
+You can then upload the ``manylinux2014`` wheels to pypi using `twine <https://github.com/pypa/twine>`_.
+
+It is possible to use any of the ``manylinux`` docker images: ``manylinux1``, ``manylinux2010`` or ``manylinux2014``. (Just replace ``manylinux2014`` in the above instructions with the alternative version you wish to use.)
+
+Binary wheels on macOS
+^^^^^^^^^^^^^^^^^^^^^^
+
+For building wheels on macOS it is sufficient to run the ``bdist_wheel`` command, i.e. ``setup.py bdist_wheel``.
+
+To build ``universal2`` wheels set the ``ARCHFLAGS`` environment variable to contain both ``x86_64`` and ``arm64``, for example ``ARCHFLAGS="-arch x86_64 -arch arm64"``. Wheel-building solutions such as `cibuildwheel`_ set this environment variable automatically.
+
+.. _cibuildwheel: https://github.com/pypa/cibuildwheel

docs/conf.py

@@ -26,7 +26,6 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",
     "sphinx_autodoc_typehints",
-    "sphinx_rtd_theme",
     "m2r2",
 ]
 
@@ -44,16 +43,14 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "sphinx_rtd_theme"
+html_theme = "furo"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 
-html_theme_options = {
-    "prev_next_buttons_location": None,
-}
+html_theme_options = {}
 
 # -- Custom HTML link transformation to make documentation links relative --
 
@@ -70,7 +67,7 @@ class RelativeDocLinks(SphinxTransform):
     default_priority = 750
 
     def apply(self):
-        from docutils.nodes import reference, Text
+        from docutils.nodes import Text, reference
 
         baseref = lambda o: (
             isinstance(o, reference) and o.get("refuri", "").startswith(DOCS_URL)

docs/index.rst

@@ -3,6 +3,7 @@
    :hidden:
 
    README
+   building_wheels
    reference
 
 .. include:: README.rst

docs/requirements.txt

@@ -1,4 +1,4 @@
-m2r2==0.2.7
-Sphinx==3.5.2
-sphinx-autodoc-typehints==1.11.1
-sphinx-rtd-theme==0.5.1
+m2r2==0.3.1
+Sphinx==4.1.2
+sphinx-autodoc-typehints==1.12.0
+furo==2021.8.31

setuptools_rust/extension.py

@@ -3,14 +3,14 @@
 from distutils.errors import DistutilsSetupError
 from enum import IntEnum, auto
 from typing import Dict, List, Optional, Union
-from typing_extensions import Literal
 
 import semantic_version
+from typing_extensions import Literal
 
 
 class Binding(IntEnum):
     """
-    Enumeration of possible Rust binding types supported by `setuptools-rust`.
+    Enumeration of possible Rust binding types supported by ``setuptools-rust``.
 
     Attributes:
         PyO3: This is an extension built using