gh-122085: Use include files for C API deprecations #109843
Conversation
|
If you move these sub-sections of the C API section, you should also move the other ones of the "main" Python section: moving "Pending Removal in Python 3.14" after Removal. What do you think?
|
|
Personally, I probably wouldn't as I think semantically it makes more sense to note the pending removals for Python APIs within the Deprecated section -- they are a concise list of how quickly readers will need to adapt to the new APIs. A |
My concern is more that these lists are getting bigger at every Python version. Sometimes, I'm considering to create a sub-page of What's New in Python 3.13, since the document is so big, that people may give up to just start reading it. Deprecation/Removal only interest a minority of people. The whole What's New in Python 3.13 takes 18 pages if I print it as PDF with my default browser configuration. I don't have a strong opinon between:
VERSUS:
I would just prefer to have consistency between the (main) Python section and the C API Changes section. If you prefer to have "Pending Removals ..." under the Deprecations section, please just make it consistent in the doc. |
I agree with this. I want us to have a static page of pending deprecations, so we don't need to worry synchronising across both pages (3.14.rst <-> 3.13.rst <-> 3.12.rst etc.) and branches (main <-> 3.13 <-> 3.12). And we sometimes do forget to update them, for example #118947. Additionally, at some point a branch goes to security-fix only, and we can no longer update the What's New. Then, in "What's New in Python 3.x", we should only list the deprecations newly added in that release. Compare the pytest page: As a user of pytest, this is a useful one-stop page to look where I need to update my code. I copied it for Pillow: As a maintainer of Pillow, this is a useful one-stop page to look for old deprecations to remove in the next release. |
|
(OK, I can see that there is more to this than I originally thought) It seems like the current consensus is to have something like and possibly some |
|
Follow on from this. We discussed this on Discourse: And in the docs-community meeting last month, where we thought about using includes: Please see PR #121241 to make a start on this. |
fec9587 to
97193bc
Compare
|
With apologies for the force-push, I have hijacked my own PR to use the include-file approach for the C API, whilst still doing the synchronisation. I've split the work into individual commits, which should be somewhat easy to follow. A |
|
Is it so that we weren't previously duplicating all the C API deprecations across What's New files? This will mean the What's New pages will become even longer. But I suppose if we do it for the Python deprecations, that's an argument for also doing it for the C API ones too. |
Almost all of the deprecations were in both 3.12 and 3.13, it was only 3.14 that was sparse, so I think it is worth both ensuring there's consistency and that we advertise the deprecations in all What's New pages. A |
|
Would you like to add these includes to the new I also realised we don't want cpython/Doc/deprecations/index.rst Line 4 in b359f66 The backports are correct:
Please could you also remove that line at the same time? |
Done
Done A |
|
Thanks @AA-Turner for the PR 🌮🎉.. I'm working now to backport this PR to: 3.12, 3.13. |
|
Sorry, @AA-Turner, I could not cleanly backport this to |
|
Sorry, @AA-Turner, I could not cleanly backport this to |
…honGH-109843) (cherry picked from c 9E88 ommit 76bdfa4) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
|
GH-122422 is a backport of this pull request to the 3.13 branch. |
…honGH-109843) (cherry picked from commit 76bdfa4) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
|
GH-122423 is a backport of this pull request to the 3.12 branch. |
📚 Documentation preview 📚: https://cpython-previews--109843.org.readthedocs.build/