Add Pixi workflow to verify Pyodide build works

.gitattributes

@@ -1,2 +1,4 @@
 docs/* linguist-documentation
 releasenotes/* linguist-documentation
+# SCM syntax highlighting & preventing 3-way merges
+pixi.lock merge=binary linguist-language=YAML linguist-generated=true

.github/workflows/main.yml

@@ -195,3 +195,16 @@ jobs:
         with:
           name: html_docs
           path: docs/build/html
+  pyodide-build:
+    if: github.repository_owner == 'Qiskit'
+    needs: [tests]
+    name: Pyodide Build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: prefix-dev/setup-pixi@v0.9.3
+        with:
+          manifest-path: pyproject.toml
+          pixi-version: v0.61.0
+          environments: default
+      - run: pixi run build_pyodide

.gitignore

@@ -25,3 +25,10 @@ rustworkx-core/Cargo.lock
 **/.DS_Store
 venv/
 .python-version
+
+# pixi environments
+.pixi
+*.egg-info
+
+# pyodide xbuild
+.xbuildenv

CONTRIBUTING.md

@@ -560,6 +560,80 @@ has the necessary approvals and is tagged as `automerge` unless it has a merge
 conflict or has a failed CI run. Doing so will just waste CI resources and
 delay everything from merging, including your PR.
 
+### Pyodide Support
+
+`rustworkx` has experimental support for Pyodide, the Python distribution for
+the browser.
+
+Because building for Pyodide is a more involved process, we use [Pixi](https://pixi.sh/latest/)
+to manage the dependencies of the build. Currently, the scripts work only for Linux x86-64 and macOS arm64.
+It is also possible to run the build on Windows with Windows Subsystem for Linux (WSL).
+
+Please refer to the [Pixi](https://pixi.sh/latest/) page for the latest instructions on how
+to install Pixi. Once installed, there's a single command that needs to be run.
+
+#### Building for Pyodide
+
+At the root of the directory, simply run:
+
+```bash
+pixi run build_pyodide
+```
+
+This will create a separate environment with all of the required toolchains. At the end,
+a Pyodide wheel will be available in the `dist` folder if the build is successful.
+
+#### Testing Pyodide Wheels
+
+Currently, there are no tests for Pyodide wheels. In the future, we plan to add smoke tests
+like those in the `pyodide-recipes` repository.
+
+#### Updating `pyodide-build` and dependencies
+
+All the dependencies for the Pyodide build are listed under `[tool.pixi.dependencies]`. To find a set
+of versions that works, visit the [pyodide-cross-build-environments.json](https://github.com/pyodide/pyodide/blob/main/pyodide-cross-build-environments.json) file in the `pyodide` repository.
+
+Pixi pulls dependencies from `conda-forge`. Therefore, we need to work with versions published in the [Emscripten feedstock for Conda Forge](https://anaconda.org/conda-forge/emscripten).  Because of the constraints imposed by Pixi, some Pyodide versions will not work with the script as the required Emscripten version is not in Conda Forge.
+
+Once a Pyodide version with a matching Emscripten version has been picked, we need to select a `pyodide-build` version. `pyodide-build` is less tricky because we have a minimum version and not a pinned version. Select any version higher than the required build version and the equivalent Python
+version.
+
+Once all versions are picked, update `[tool.pixi.tasks.install_xbuildenv]` accordingly. For example, the following entry from `pyodide-cross-build-environments.json`: 
+
+```json
+"0.27.7": {
+    "version": "0.27.7",
+    "python_version": "3.12.7",
+    "emscripten_version": "3.1.58",
+    "min_pyodide_build_version": "0.26.0"
+}
+```
+
+Becomes:
+```toml
+[tool.pixi.dependencies]
+python = "==3.12.7"
+pyodide-build = "==0.30.9"
+emscripten = "==3.1.58"
+
+[tool.pixi.tasks.install_xbuildenv]
+cmd = ["pyodide", "xbuildenv", "install", "0.27.7"]
+```
+
+Lastly, we need to pin the Rust compiler. To find an appropriate Rust compiler version, run:
+
+```bash
+pixi shell
+pyodide config list
+```
+
+This will output a list including `rust_toolchain`. Currently, `pyodide-build` requires Rust Nightly. Because conda-forge
+only provides stable releases, we'll need to map a nightly version to a stable version. Some repositories like [oxalica/rust-overlay](https://github.com/oxalica/rust-overlay/tree/master/manifests/nightly/) contain a list of the nightly releases. For example, `nightly-2025-02-01`
+maps roughly to `1.86`. If that version was not yet stable, we could try picking `1.85` as well.
+
+After updating the versions in `[tool.pixi.dependencies]`, run `pixi lock` which will update `pixi.lock`. Onwards, all builds
+will use the same environment. As long as `pixi run build_pyodide` passes locally or on CI it should keep compiling and building.
+
 ### Stable Branch Policy and Backporting
 
 The stable branch is intended to be a safe source of fixes for high-impact bugs,

docs/source/install.rst

@@ -117,6 +117,10 @@ source.
      - WASM (Emscripten)
      - :ref:`tier-experimental`
      -
+   * - Pyodide 
+     - WASM (Emscripten)
+     - :ref:`tier-experimental`
+     -
 
 
 .. _manylinux 2014: https://peps.python.org/pep-0599/>