docs: rust (#1816)

* docs: add FAQ entry on Rust

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

* ci: make readthedocs faster

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

* Update docs/faq.md

* Update docs/faq.md

* Update faq.md

* Update docs/faq.md

* Update docs/faq.md

Co-authored-by: Matthieu Darbois <mayeut@users.noreply.github.com>

* Apply suggestions from code review

---------

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>
Co-authored-by: Matthieu Darbois <mayeut@users.noreply.github.com>

.readthedocs.yml

@@ -5,14 +5,11 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.11"
+    python: "3.12"
-
+  commands:
-python:
+    - asdf plugin add uv
-  install:
+    - asdf install uv latest
-    - method: pip
+    - asdf global uv latest
-      path: .
+    - uv venv
-      extra_requirements:
+    - uv pip install .[docs]
-        - docs
+    - .venv/bin/python -m mkdocs build --site-dir $READTHEDOCS_OUTPUT/html
-
-mkdocs:
-  configuration: mkdocs.yml

README.md

@@ -307,4 +307,4 @@ See also
 
 Another very similar tool to consider is [matthew-brett/multibuild](http://github.com/matthew-brett/multibuild). `multibuild` is a shell script toolbox for building a wheel on various platforms. It is used as a basis to build some of the big data science tools, like SciPy.
 
-If you are building Rust wheels, you can get by without some of the tricks required to make GLIBC work via manylinux; this is especially relevant for cross-compiling, which is easy with Rust. See [maturin-action](https://github.com/messense/maturin-action) for a tool that is optimized for building Rust wheels and cross-compiling.
+If you are building Rust wheels, you can get by without some of the tricks required to make GLIBC work via manylinux; this is especially relevant for cross-compiling, which is easy with Rust. See [maturin-action](https://github.com/PyO3/maturin-action) for a tool that is optimized for building Rust wheels and cross-compiling.

docs/faq.md

@@ -282,6 +282,27 @@ For these reasons, it's strongly recommended to not use brew for native library
 [Homebrew]: https://brew.sh/
 [delocate]: https://github.com/matthew-brett/delocate
 
+### Building Rust wheels
+
+If you build Rust wheels, you need to download the Rust compilers in manylinux.
+If you support 32-bit Windows, you need to add this as a potential target. You
+can do this on GitHub Actions, for example, with:
+
+```yaml
+CIBW_BEFORE_ALL_LINUX: curl -sSf https://sh.rustup.rs | sh -s -- -y
+CIBW_BEFORE_ALL_WINDOWS: rustup target add i686-pc-windows-msvc
+CIBW_ENVIRONMENT_LINUX: "PATH=$HOME/.cargo/bin:$PATH"
+```
+
+Rust does not provide Cargo for musllinux 32-bit, so that needs to be skipped:
+
+```toml
+[tool.cibuildwheel]
+skip = ["*-musllinux_i686"]
+```
+
+Also see [maturin-action](https://github.com/PyO3/maturin-action) which is optimized for Rust wheels, builds the non-Python Rust modules once, and can cross-compile (and can build 32-bit musl, for example).
+
 ### macOS: ModuleNotFoundError
 
 Calling cibuildwheel from a python3 script and getting a `ModuleNotFoundError`? Due to a (fixed) [bug](https://bugs.python.org/issue22490) in CPython, you'll need to [unset the `__PYVENV_LAUNCHER__` variable](https://github.com/pypa/cibuildwheel/issues/133#issuecomment-478288597) before activating a venv.