gh-122085: Use include files for C API deprecations

[AA-Turner]

---

📚 Documentation preview 📚: https://cpython-previews--109843.org.readthedocs.build/

• Issue: Docs: move deprecations into include files #122085

[vstinner]

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?

[AA-Turner]

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

[vstinner]

they are a concise list

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:

• Deprecations

  • Pending Removals ...

• Removal

VERSUS:

• Deprecations
• Removal
• Pending Removals ...

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.

[blaisep]

The text is cleaner than before, thank you.
I can't confirm that the content is correct, I hope this gets merged soon.

[hugovk]

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.

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:

• https://docs.pytest.org/en/latest/deprecations.html

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:

• https://pillow.readthedocs.io/en/stable/deprecations.html

As a maintainer of Pillow, this is a useful one-stop page to look for old deprecations to remove in the next release.

[blaisep]

(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

Doc/whatsnew/deprecations/removal.rst Doc/whatsnew/deprecations/removalpending.rst Doc/whatsnew/deprecations/deprecations.rst 

and possibly some Doc/whatsnew/deprecations/index.rst with a bit of .. toctree:: sugar sprinkles?
Shall I bring this up in the docs discord?

[hugovk]

Follow on from this. We discussed this on Discourse:

• https://discuss.python.org/t/streamline-whats-new-by-moving-deprecations-and-removals-out-of-news/53997

And in the docs-community meeting last month, where we thought about using includes:

• https://docs-community.readthedocs.io/en/latest/monthly-meeting/2024-06.html#python-project-documentation

• https://discuss.python.org/t/streamline-whats-new-by-moving-deprecations-and-removals-out-of-news/53997/8

Please see PR #121241 to make a start on this.

[AA-Turner]

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

[hugovk]

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.

[AA-Turner]

Is it so that we weren't previously duplicating all the C API deprecations across What's New files?

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

[hugovk]

Would you like to add these includes to the new deprecations/index.rst from #122352?

---

I also realised we don't want .. include:: pending-removal-in-3.14.rst here in main (aka 3.14), we only want to list later versions:

cpython/Doc/deprecations/index.rst

Line 4 in b359f66

.. include:: pending-removal-in-3.14.rst

The backports are correct:

• https://github.com/python/cpython/blob/3.13/Doc/deprecations/index.rst
• https://github.com/python/cpython/blob/3.12/Doc/deprecations/index.rst

Please could you also remove that line at the same time?

[AA-Turner]

Would you like to add these includes to the new deprecations/index.rst

Done

Please could you also remove that line at the same time?

Done

A

[hugovk]

Thanks!

[miss-islington-app]

Thanks @AA-Turner for the PR 🌮🎉.. I'm working now to backport this PR to: 3.12, 3.13.
🐍🍒⛏🤖 I'm not a witch! I'm not a witch!

[miss-islington-app]

Sorry, @AA-Turner, I could not cleanly backport this to 3.13 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 76bdfa4cd02532519fb43ae91244e2b4b3650d78 3.13 

[miss-islington-app]

Sorry, @AA-Turner, I could not cleanly backport this to 3.12 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 76bdfa4cd02532519fb43ae91244e2b4b3650d78 3.12 

[bedevere-app]

GH-122422 is a backport of this pull request to the 3.13 branch.

[bedevere-app]

GH-122423 is a backport of this pull request to the 3.12 branch.