posit-dev / posit-dev/great-docs

feature: support documentation of `WHEELS.md` for Python project docs

Open
#312 0 comments 0 reactions 1 assignee View on GitHub

@rich-iannone is already working on this.

Since Aug 10, 2026.

Difficulty: [1] Novice Effort: [2] Medium Priority: [2] Medium Type: ★ Enhancement
Dominant language
Python
Stars
262
Forks
18
Avg merge
1d 4h
Merged PRs (30d)
14

Description

Compiled Python packages distribute pre-built wheels for specific platforms, Python versions, and architectures. This info can be important to know for downstream consumers and contributors but is currently scattered across pyproject.toml, CI configs, and PyPI. So there's no single in-repo source of truth.

The proposal here is to recognize a WHEELS.md convention at the repo root and render it as a page accessible from the package info section of the homepage sidebar. For packages without one, Great Docs could auto-generate a basic version from pyproject.toml metadata (requires-python, classifiers) and [tool.cibuildwheel] config. Packages with more complex build stories (abi3 stable ABI, Pyodide/WASM wheels, skipped platforms) would maintain their own WHEELS.md to document the full picture.

Recently in posit-dev/multimark I added a WHEELS.md that covers native abi3 wheels, Pyodide/emscripten wheels, platform matrix, local build commands, and pre-release testing workflows.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.