DOC: improve docs for limited api builds - #885
Conversation
rgommers
left a comment
rgommers
left a comment
There was a problem hiding this comment.
Thanks @ngoldbaum for writing docs for the Limited API! Overall this content looks like a great start. My main comment right now is that it's not in the right places: it can't be in the reference guide, and the examples section of the "Passing arguments to Meson" page also feels wrong. I think we need a new page, as a how-to under "Using shared libraries" called something like "Using the Limited C API" or some such title.
This content, put together in a single page, will be a great start. I have a few things I'd like to add, like how to set it up as opt-in (e.g., as in PyWavelets/pywt#828).
We can then also address a couple of open issues: gh-624, some parts of gh-787.
| sufficient to compile the extension modules for ``abi3t`` when | ||
| building with free-threaded CPython 3.15 or later. Building | ||
| ``abi3t`` extension modules with a GIL-enabled interpreter is not | ||
| supported, see `Meson issue 15637`_. |
There was a problem hiding this comment.
Let's just say "not supported yet". We don't link issues from the docs, and there isn't much of interest to see anyway in that issue for the average user.
| value ``abi3`` is used for the Python wheel filename ABI tag. | ||
| Python wheel filename ABI tag is set to the stable ABI tag: | ||
| ``abi3`` when building with GIL-enabled CPython, and ``abi3.abi3t`` | ||
| when building with free-threaded CPython 3.15 or later, see below. |
There was a problem hiding this comment.
We want to keep the reference guide content very short and to the point. The above three sentences are enough on this page I'd say. Then reference the detailed docs for more info. That's where the below content should move.
|
I rearranged with a new howto guide page. Let me know what you think. |
2 participants
I'm planning to add a section on meson-python abi3t builds in the free-threaded guide. See Quansight-Labs/free-threaded-compatibility#341 which has a stub for meson-python right now.
Ideally I'd like this section to be brief and mostly be linking to the meson-python docs.
I noticed that #856 didn't have any docs and the existing docs on limited API builds are a little thin. Since abi3t adds complexity and some issues for builds on 3.14, I think it's worth adding some more docs.
Let me know if you'd prefer I trim this down some or otherwise do this differently.