From 0e71c5a96f450a90f32207344f90d7df9a154444 Mon Sep 17 00:00:00 2001 From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com> Date: Wed, 27 May 2026 09:16:23 +0530 Subject: [PATCH 01/10] Add `sphinx-click` as a dependency --- docs/requirements-doc.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/requirements-doc.txt b/docs/requirements-doc.txt index 0ae1b9f6..4581d760 100644 --- a/docs/requirements-doc.txt +++ b/docs/requirements-doc.txt @@ -3,3 +3,4 @@ sphinx_book_theme>=0.4.0rc1 myst-parser sphinx-autodoc-typehints>=1.21.7 sphinx-design +sphinx-click From 5d93cf7ec9d8446281e57a7dc1b1323f923c9343 Mon Sep 17 00:00:00 2001 From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com> Date: Wed, 27 May 2026 09:16:44 +0530 Subject: [PATCH 02/10] Register `sphinx_click` Sphinx extension --- docs/conf.py | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/conf.py b/docs/conf.py index 9db41351..ef4d4549 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -16,6 +16,7 @@ "myst_parser", "sphinx_autodoc_typehints", "sphinx_design", + "sphinx_click", ] myst_enable_extensions = [ From c78e90d3f4fdf99e6059a2860c3860a6e62ebbe0 Mon Sep 17 00:00:00 2001 From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com> Date: Wed, 27 May 2026 09:17:47 +0530 Subject: [PATCH 03/10] Replace manual writeups with click directives --- docs/reference/cli.md | 144 +++--------------------------------------- 1 file changed, 10 insertions(+), 134 deletions(-) diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 3a768cbc..7ad118c5 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -4,150 +4,26 @@ All commands are accessed through the `pyodide` CLI, provided by the [pyodide-cl ## pyodide build -Build a Python package for WebAssembly. - -``` -pyodide build [OPTIONS] [SOURCE_LOCATION] +```{click} pyodide_build.cli.build:main +:prog: pyodide build ``` -**Arguments:** - -| Argument | Description | -|---|---| -| `SOURCE_LOCATION` | Build source: a directory. Defaults to the current directory. | - -**Options:** - -| Option | Default | Description | -|---|---|---| -| `-o`, `--outdir` | `./dist` | Output directory for the built wheel | -| `--exports` | `requested` | Symbol export mode: `pyinit`, `requested`, `whole_archive`, or comma-separated list | -| `-C`, `--config-setting` | | Pass settings to the build backend (same as `pypa/build`) | -| `-n`, `--no-isolation` | `false` | Disable build isolation; build deps must be installed manually | -| `-x`, `--skip-dependency-check` | `false` | Skip build dependency check (only with `--no-isolation`) | -| `--compression-level` | `6` | Zip compression level for the wheel | -| `--xbuildenv-path` | platform cache | Path to the cross-build environment, inferred from platform cache if not specified | - ## pyodide venv -Create a Pyodide virtual environment for testing. - +```{click} pyodide_build.cli.venv:main +:prog: pyodide venv ``` -pyodide venv [OPTIONS] DEST -``` - -**Arguments:** - -| Argument | Description | -|---|---| -| `DEST` | Directory to create the virtualenv at | - -**Options:** - -| Option | Default | Description | -|---|---|---| -| `--clear` / `--no-clear` | `no-clear` | Remove destination directory if it exists | -| `--no-vcs-ignore` | | Don't create VCS ignore directive (e.g., `.gitignore`) | -| `--download` / `--no-download` | | Enable/disable download of latest pip/setuptools from PyPI | -| `--extra-search-dir` | | Path containing additional wheels | -| `--pip` | `bundle` | pip version: `embed`, `bundle`, or exact version | -| `--setuptools` | | setuptools version: `embed`, `bundle`, `none`, or exact version | -| `--no-setuptools` | | Do not install setuptools | ## pyodide config -Query build configuration values. - -### pyodide config list - -``` -pyodide config list -``` - -Lists all config variables and their current values. - -### pyodide config get - -``` -pyodide config get CONFIG_VAR +```{click} pyodide_build.cli.config:app +:prog: pyodide config +:nested: full ``` -Get a single config variable's value. Common variables: - -| Variable | Description | -|---|---| -| `cflags` | C compiler flags | -| `cxxflags` | C++ compiler flags | -| `ldflags` | Linker flags | -| `rustflags` | Rust compiler flags | -| `cmake_toolchain_file` | Path to CMake toolchain file | -| `meson_cross_file` | Path to Meson cross file | -| `rust_toolchain` | Required Rust nightly toolchain | -| `emscripten_version` | Required Emscripten version | -| `python_version` | Target Python version | -| `xbuildenv_path` | Cross-build environment path | -| `pyodide_abi_version` | Pyodide ABI version | - ## pyodide xbuildenv -Manage the cross-build environment. - -### pyodide xbuildenv install - -``` -pyodide xbuildenv install [OPTIONS] [VERSION] +```{click} pyodide_build.cli.xbuildenv:app +:prog: pyodide xbuildenv +:nested: full ``` - -| Option | Env var | Description | -|---|---|---| -| `--path` | `PYODIDE_XBUILDENV_PATH` | Destination directory | -| `--url` | | Download from a custom URL | -| `-f`, `--force` | | Force install even if version is incompatible | -| `--nightly` | | Install a nightly release instead of a stable one | -| `--debug` | | Install the debug variant of a nightly or stable release, as available | - -### pyodide xbuildenv version - -``` -pyodide xbuildenv version [--path PATH] -``` - -Print the current active version. - -### pyodide xbuildenv versions - -``` -pyodide xbuildenv versions [--path PATH] -``` - -List all installed versions. Active version is marked with `*`. - -### pyodide xbuildenv use - -``` -pyodide xbuildenv use VERSION [--path PATH] -``` - -Switch to a specific installed version. - -### pyodide xbuildenv uninstall - -``` -pyodide xbuildenv uninstall [VERSION] [--path PATH] -``` - -Uninstall a version. Defaults to the current version if not specified. - -### pyodide xbuildenv search - -``` -pyodide xbuildenv search [OPTIONS] -``` - -| Option | Description | -|---|---| -| `--metadata` | Custom metadata file URL or path (cannot be combined with `--nightly`/`--debug`) | -| `-a`, `--all` | Show all versions, including incompatible ones | -| `--nightly` | Search nightly releases instead of stable ones | -| `--debug` | Search nightly debug releases instead of stable ones | -| `--json` | Output as JSON | From a018fb07145eb768ed511c37e1eda2e8619dfeb7 Mon Sep 17 00:00:00 2001 From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com> Date: Wed, 27 May 2026 10:03:35 +0530 Subject: [PATCH 04/10] Drop `requirements-doc.txt` --- .readthedocs.yaml | 13 +++++++------ docs/requirements-doc.txt | 6 ------ pyproject.toml | 2 ++ 3 files changed, 9 insertions(+), 12 deletions(-) delete mode 100644 docs/requirements-doc.txt diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 15b7b977..2f6e6b14 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -6,13 +6,14 @@ sphinx: formats: [] -python: - install: - - requirements: docs/requirements-doc.txt - - method: pip - path: . - build: os: ubuntu-24.04 tools: python: "3.13" + uv: latest + jobs: + install: + - uv sync --group docs + build: + html: + - uv run sphinx-build -T -E -b html docs/ $READTHEDOCS_OUTPUT/html diff --git a/docs/requirements-doc.txt b/docs/requirements-doc.txt deleted file mode 100644 index 4581d760..00000000 --- a/docs/requirements-doc.txt +++ /dev/null @@ -1,6 +0,0 @@ -sphinx>=5.3.0 -sphinx_book_theme>=0.4.0rc1 -myst-parser -sphinx-autodoc-typehints>=1.21.7 -sphinx-design -sphinx-click diff --git a/pyproject.toml b/pyproject.toml index 5fa82462..e455a789 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -77,6 +77,8 @@ docs = [ "sphinx_book_theme>=0.4.0rc1", "myst-parser", "sphinx-autodoc-typehints>=1.21.7", + "sphinx-design", + "sphinx-click", ] [tool.hatch.version] From fe098ec3b20bfdfbf7f4b6a42322c02f360a320a Mon Sep 17 00:00:00 2001 From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com> Date: Wed, 27 May 2026 10:05:03 +0530 Subject: [PATCH 05/10] Pin to Sphinx<9 --- pyproject.toml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index e455a789..0b58a85e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -73,7 +73,10 @@ test = [ "click>=8.0,<8.3.3", ] docs = [ - "sphinx>=5.3.0", + # sphinx-click 6.2.0 is broken with Sphinx 9 due to a mock resolution issue. + # see https://github.com/click-contrib/sphinx-click/pull/160. We can remove + # this when merged and released. + "sphinx>=5.3.0,<9", "sphinx_book_theme>=0.4.0rc1", "myst-parser", "sphinx-autodoc-typehints>=1.21.7", From 4c1e1ef303a695ebcf6cca556617140c4f7bb410 Mon Sep 17 00:00:00 2001 From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com> Date: Wed, 27 May 2026 10:07:24 +0530 Subject: [PATCH 06/10] Add automated sphinx-click directives --- docs/conf.py | 44 +++++++++++++++++++++++++++++++++++++++++++ docs/reference/cli.md | 26 ++----------------------- 2 files changed, 46 insertions(+), 24 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index ef4d4549..22dab326 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -3,6 +3,9 @@ from importlib import metadata as importlib_metadata from pathlib import Path +from docutils import nodes, statemachine +from sphinx.util.docutils import SphinxDirective + project = "pyodide-build" copyright = "2019-2026, Pyodide contributors" @@ -61,3 +64,44 @@ release = "0.0.0" version = release + + +# -- Auto-generated CLI reference -------------------------------------------- + + +class PyodideCLIReference(SphinxDirective): + """ + Emit a sphinx-click block for a ``pyodide.cli`` entry point if it belongs + to pyodide-build, to automatically generate CLI reference documentation. + """ + + def run(self) -> list[nodes.Node]: + entry_points = sorted( + ( + entry_point + for entry_point in importlib_metadata.entry_points(group="pyodide.cli") + if entry_point.dist is not None + and entry_point.dist.name == "pyodide-build" + ), + key=lambda ep: ep.name, + ) + + rst: list[str] = [] + for ep in entry_points: + obj = ep.load() + rst.append(f".. click:: {ep.value}") + rst.append(f" :prog: pyodide {ep.name}") + if hasattr( + obj, "commands" + ): # If it's a click group? Then let's recurse into subcommands + rst.append(" :nested: full") + rst.append("") + + result = statemachine.ViewList(rst, source="") + node: nodes.Node = nodes.section() + self.state.nested_parse(result, self.content_offset, node) + return node.children + + +def setup(app): + app.add_directive("pyodide-cli-reference", PyodideCLIReference) diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 7ad118c5..03fd0764 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -2,28 +2,6 @@ All commands are accessed through the `pyodide` CLI, provided by the [pyodide-cli](https://pypi.org/project/pyodide-cli/) package (installed automatically with pyodide-build). -## pyodide build - -```{click} pyodide_build.cli.build:main -:prog: pyodide build -``` - -## pyodide venv - -```{click} pyodide_build.cli.venv:main -:prog: pyodide venv -``` - -## pyodide config - -```{click} pyodide_build.cli.config:app -:prog: pyodide config -:nested: full -``` - -## pyodide xbuildenv - -```{click} pyodide_build.cli.xbuildenv:app -:prog: pyodide xbuildenv -:nested: full +```{eval-rst} +.. pyodide-cli-reference:: ``` From 61432ecbbf7bb35c71eb623eab857f88ad26ada3 Mon Sep 17 00:00:00 2001 From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com> Date: Wed, 27 May 2026 10:17:15 +0530 Subject: [PATCH 07/10] Ah `uv` can't be specified under `tools` --- .readthedocs.yaml | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 2f6e6b14..611854b7 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -10,10 +10,10 @@ build: os: ubuntu-24.04 tools: python: "3.13" - uv: latest - jobs: - install: - - uv sync --group docs - build: - html: - - uv run sphinx-build -T -E -b html docs/ $READTHEDOCS_OUTPUT/html + +python: + install: + - method: uv + command: sync + groups: + - docs From 03f0e9d461a7ebfeed04a3f0a8be43d55ee91507 Mon Sep 17 00:00:00 2001 From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com> Date: Wed, 27 May 2026 19:10:59 +0530 Subject: [PATCH 08/10] Exclude some recipe-related commands --- docs/conf.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 22dab326..7f3732d1 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -75,6 +75,10 @@ class PyodideCLIReference(SphinxDirective): to pyodide-build, to automatically generate CLI reference documentation. """ + # Recipe-related commands are intentionally excluded: they are not relevant + # to most users building out-of-tree packages. + _EXCLUDE = {"build-recipes", "build-recipes-no-deps", "skeleton"} + def run(self) -> list[nodes.Node]: entry_points = sorted( ( @@ -82,6 +86,7 @@ def run(self) -> list[nodes.Node]: for entry_point in importlib_metadata.entry_points(group="pyodide.cli") if entry_point.dist is not None and entry_point.dist.name == "pyodide-build" + and entry_point.name not in self._EXCLUDE ), key=lambda ep: ep.name, ) From 254784250645977a11e1515e5d60d3087891e750 Mon Sep 17 00:00:00 2001 From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com> Date: Wed, 27 May 2026 19:13:32 +0530 Subject: [PATCH 09/10] Update the Pyodide config variable table --- docs/reference/configuration.md | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index 90fff9fc..099dc391 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -25,18 +25,26 @@ xbuildenv_path = "/path/to/xbuildenv" ## User-overridable settings -These keys can be set in `pyproject.toml` or via environment variables: +These keys can be set in `pyproject.toml` under `[tool.pyodide.build]` or via environment variables: | pyproject.toml key | Env variable | Description | |---|---|---| -| `cflags` | `CFLAGS` | C compiler flags | -| `cxxflags` | `CXXFLAGS` | C++ compiler flags | -| `ldflags` | `LDFLAGS` | Linker flags | +| `cflags` | `SIDE_MODULE_CFLAGS` | C compiler flags | +| `cxxflags` | `SIDE_MODULE_CXXFLAGS` | C++ compiler flags | +| `ldflags` | `SIDE_MODULE_LDFLAGS` | Linker flags | | `rustflags` | `RUSTFLAGS` | Rust compiler flags | -| `rust_toolchain` | `RUST_TOOLCHAIN` | Rust nightly toolchain version | -| `meson_cross_file` | `MESON_CROSS_FILE` | Path to Meson cross file | -| `xbuildenv_path` | `PYODIDE_XBUILDENV_PATH` | Path to cross-build environment | -| `ignored_build_requirements` | `IGNORED_BUILD_REQUIREMENTS` | Build requirements to ignore | +| `rust_toolchain` | `RUST_TOOLCHAIN` | Required Rust nightly toolchain | +| `rust_emscripten_target_url` | `RUST_EMSCRIPTEN_TARGET_URL` | URL for the Rust Emscripten target | +| `meson_cross_file` | `MESON_CROSS_FILE` | Path to the Meson cross file | +| `xbuildenv_path` | `PYODIDE_XBUILDENV_PATH` | Path to the cross-build environment | +| `ignored_build_requirements` | `IGNORED_BUILD_REQUIREMENTS` | Space-separated PEP 508 build requirements to ignore | +| `skip_emscripten_version_check` | `SKIP_EMSCRIPTEN_VERSION_CHECK` | Skip Emscripten version compatibility check (`0`/`1`) | +| `build_dependency_index_url` | `BUILD_DEPENDENCY_INDEX_URL` | PyPI index URL for host-side build dependencies | +| `default_cross_build_env_url` | `DEFAULT_CROSS_BUILD_ENV_URL` | URL override for the cross-build environment archive | +| `use_legacy_platform` | `USE_LEGACY_PLATFORM` | Use the legacy `pyodide_*` platform tag instead of `pyemscripten_*` (`0`/`1`) | + +Run `pyodide config list` to see all available variables and their current values. + ## Environment variables From f21c4775589e47cc1fb1283ca910fc90d0adff67 Mon Sep 17 00:00:00 2001 From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com> Date: Wed, 3 Jun 2026 13:24:24 +0530 Subject: [PATCH 10/10] Some changes to the table Co-Authored-By: Gyeongjae Choi --- docs/reference/configuration.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index 099dc391..48238c73 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -29,17 +29,15 @@ These keys can be set in `pyproject.toml` under `[tool.pyodide.build]` or via en | pyproject.toml key | Env variable | Description | |---|---|---| -| `cflags` | `SIDE_MODULE_CFLAGS` | C compiler flags | -| `cxxflags` | `SIDE_MODULE_CXXFLAGS` | C++ compiler flags | -| `ldflags` | `SIDE_MODULE_LDFLAGS` | Linker flags | +| `cflags` | `CFLAGS` | C compiler flags | +| `cxxflags` | `CXXFLAGS` | C++ compiler flags | +| `ldflags` | `LDFLAGS` | Linker flags | | `rustflags` | `RUSTFLAGS` | Rust compiler flags | | `rust_toolchain` | `RUST_TOOLCHAIN` | Required Rust nightly toolchain | -| `rust_emscripten_target_url` | `RUST_EMSCRIPTEN_TARGET_URL` | URL for the Rust Emscripten target | | `meson_cross_file` | `MESON_CROSS_FILE` | Path to the Meson cross file | | `xbuildenv_path` | `PYODIDE_XBUILDENV_PATH` | Path to the cross-build environment | | `ignored_build_requirements` | `IGNORED_BUILD_REQUIREMENTS` | Space-separated PEP 508 build requirements to ignore | | `skip_emscripten_version_check` | `SKIP_EMSCRIPTEN_VERSION_CHECK` | Skip Emscripten version compatibility check (`0`/`1`) | -| `build_dependency_index_url` | `BUILD_DEPENDENCY_INDEX_URL` | PyPI index URL for host-side build dependencies | | `default_cross_build_env_url` | `DEFAULT_CROSS_BUILD_ENV_URL` | URL override for the cross-build environment archive | | `use_legacy_platform` | `USE_LEGACY_PLATFORM` | Use the legacy `pyodide_*` platform tag instead of `pyemscripten_*` (`0`/`1`) |