gh-133678: Add a banner to C API doc to recommend 3rd party tools #133679
Conversation
|
Banner added to all pages (the gray note):
Link to this new section:
|
|
I think we'll need a bit more nuance in here, explaining why we still have a C API at all if we're telling people not to use it (obvious to us, not obvious to someone who happens to be reading these docs for the first time). |
Totally agree. For example, I've personally taken a lot of information from the last discuss thread. It seems to be very useful to document these nuances in concise manner. |
|
I also think we need to be careful to indicate that these are not supported by the same people who maintain Python, and issues need to be raised with the projects directly. |
|
...and, by implication, other abstractions are not recommended? |
|
@zooba: I elaborated the rationale a little bit in the "Recommended third party tools" section. Feel free to propose better wording, I'm not good to write documentation :-) |
It's not the case. Did I miss some major abstractions in my list? |
|
The list is at least inconsistent with https://docs.python.org/dev/faq/extending.html#writing-c-is-hard-are-there-any-alternatives However my problem is with the word recommended which implies some sort of official blessing which would put new (possibly better) abstractions at a disadvantage and implies some quality control process. I'd prefer something like established or commonly used. |
IMO, this is actually a recommended API for the most of the projects. There is no direct implication that other abstraction could not be better in future. In fact, it's not a problem to add a new entry to this list, if some project had proven as a well-established alternative. But at the moment a maintainer of some project can use C API directly or through some binding. And CPython developers encourage that maintainer to use the latter. |
Co-authored-by: Steve Dower <steve.dower@microsoft.com>
Co-authored-by: Terry Jan Reedy <tjreedy@udel.edu>
There was a problem hiding this comment.
Suggested an adjustment to the banner wording. The intro to https://docs.python.org/3/extending/index.html should also be updated (potentially replacing the existing 3rd party tool list there and cross-referencing it from the C API intro rather than making a new separate list in the C API docs intro)
| class CAPIToolsBanner(SphinxDirective): | ||
| """CAPI Tools banner.""" |
There was a problem hiding this comment.
From an implementation perspective, it would be better to use an .. include:: directive rather than adding custom code here.
I don't have a strong opinion on the banner in general, but I wonder if adding it to every page is a bit much? I defer to the C API group for deliberations here, though.
A
There was a problem hiding this comment.
We've had the existing note in the extending/embedding intro for a long time, but it doesn't really work for anyone coming in from a deep link (including search results). A banner seems like a plausible improvement.
Given the possibility of anchor targets dropping people in well down the pages, though, I do wonder if a hovering banner like the ones added to finalised PEPs might be a better technical approach.
Co-authored-by: Alyssa Coghlan <ncoghlan@gmail.com>
📚 Documentation preview 📚: https://cpython-previews--133679.org.readthedocs.build/en/133679/c-api/