Auto-build project wheel for pyrepl_autodoc_packages (eliminate per-consumer build scripts)

[cursor]

Problem

Autodoc REPLs need the documented package installable in the browser via micropip. Host autodoc uses the editable install; Pyodide needs a PEP 427 wheel URL under _static/wheels/.

Today every consumer must add bespoke CI/local machinery:

pip wheel . --no-deps -w docs/_static/wheels/

…plus RTD post_install, a helper script, .gitignore entries, and a conf.py glob/version helper to set pyrepl_autodoc_packages.

Example consumer: grill-names PR #35 (scripts/build_docs_wheel.py, RTD post_install, dynamic wheel path in conf.py).

sphinx-pyrepl-web already ships scripts/build_test_pkg_wheel.py for its own fixture — same pattern duplicated downstream.

Proposal

Extend pyrepl_autodoc_packages with a project-wheel sentinel (name TBD), e.g.:

pyrepl_autodoc_packages = ":project:"   # or "wheel:."

Extension would, before doctree transforms:

1. Locate project root (config override or search upward from confdir for pyproject.toml / setup.cfg)
2. Run pip wheel <root> --no-deps -w <confdir>/_static/wheels/ (PEP 427 filename preserved)
3. Resolve packages= to _static/wheels/{distribution}-{version}-py3-none-any.whl
4. Apply existing _asset_href() normalization for nested pages

Optional config:

pyrepl_autodoc_wheel_root = None   # default: auto-detect
pyrepl_autodoc_wheel_deps = False  # pass --no-deps (micropip resolves METADATA deps)

Why not PyPI name only?

pyrepl_autodoc_packages = "my-package" works for release docs but REPL runs PyPI code, not the branch under test (RTD PR previews, unreleased changes).

Implementation notes

• Hook timing: wheel must exist before doctree-read / transform_doctest_blocks (not env-updated, which is too late on first build). builder-inited or env-before-read is appropriate.
• Output location: write to confdir/_static/wheels/ (requires html_static_path includes _static; document this). Alternatively write directly to outdir/_static/wheels/ if static copy order allows.
• Invalid filenames: micropip rejects non–PEP 427 aliases (e.g. grill-names.whl); always keep pip-generated wheel names.
• Incremental builds: skip rebuild if wheel exists and is newer than project metadata / source (mtime check).
• Scope: single-package autodoc projects (same assumption as import bootstrap). Monorepos need explicit pyrepl_autodoc_wheel_root.

Acceptance criteria

• Sentinel value builds wheel and sets packages= without consumer scripts
• Works on nested doc pages (via _asset_href)
• PyPI names and explicit _static/wheels/*.whl paths unchanged
• Integration test: fixture project, no manual wheel copy step
• README replaces manual “CI tip: cp dist/…” with sentinel docs

Related

• Add tests and docs for local .whl packages under _static/ #14 — local wheel workflow
• Local wheels, config-driven autodoc REPLs, and pyrepl-web re-vendor #16 — pyrepl_autodoc_packages + autodoc bootstrap
• grill-names consumer: Add interactive autodoc REPLs via sphinx-pyrepl-web thegrill/grill-names#35