Document `py-limited-api` option to `bdist_wheel`

[bgilbert]

To tag a wheel containing C extension modules as compatible with multiple Python releases, one must specify the undocumented py-limited-api option to bdist_wheel, setting it to the minimum Python version supported by the wheel. Otherwise the wheel will be tagged for the current Python release only, even if its C extension modules are built against the Python Limited API.

For the record, in setup.cfg this looks like:

[bdist_wheel]
py-limited-api = cp311

~Or in pyproject.toml:~ — see https://github.com/pypa/wheel/issues/582#issuecomment-1807234132

[tool.distutils.bdist_wheel]
py-limited-api = "cp311"

Or in setup.py:

setup(
    [...],
    options={'bdist_wheel': {'py_limited_api': 'cp311'}},
)

The latter is useful (alongside define_macros=[('Py_LIMITED_API', '0x...')]) if you need to programmatically disable the abi3 compatibility tag on older Python releases that haven't stabilized the API functions you need.

Please document this. I found it quite confusing: I defined Py_LIMITED_API, specified Extension(..., py_limited_api=True), and still got an incorrectly tagged wheel. It isn't necessarily obvious that setuptools and bdist_wheel don't share configuration, and the lack of documentation makes the problem hard to track down.