gh-122085: Use include files for whatsnew/3.13.rst deprecations

[hugovk]

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

This moves these sections out of "What's New in Python 3.13" into include files:

• "Pending Removal in Python 3.14"
• "Pending Removal in Python 3.15"
• "Pending Removal in Future Versions"

Later PRs will add includes to other What's New files, to avoid needing to duplicate and sync these sections between files. And we can later also create a dedicated page to list deprecations.

---

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

[nineteendo]

What happens if an entry from "Pending Removal in Future Versions" moves to "Pending Removal in Python 3.16"?
Would it be beneficial to include blank Doc/deprecations/pending-removal-in-3.*.rst up to when 3.13 will reach EOL (3.18)?

[hugovk]

Then we move it from ../deprecations/pending-removal-in-future.rst into a .. include:: ../deprecations/pending-removal-in-3.16.rst.

[nineteendo]

Yes, but then it wouldn't show up in the list of future deprecations for 3.13 if 3.16 isn't included (which would be easy to forget when added).

[hugovk]

Correct, when creating a new include file, you need to remember to add it to the relevant pages.

[encukou]

This only covers the C API, not the Python API. Is that intended?

[hugovk]

TODO: This was meant to be for the Python deprecations, not C API ones. I'll update it.

[nineteendo]

What will we do with the C API? Do we include it like this? Or do we put it in a separate file?

.. include::  ../deprecations/pending-removal-in-3.14.rst
    :start-after: .. start_pending_removal_in_3_14_capi
    :end-before: .. end_pending_removal_in_3_14_capi

[hugovk]

No, I think it would be easier to have each in their own files (not necessarily named like this):

deprecations/pending-removal-in-3.14.rst
deprecations/pending-removal-in-3.14_capi.rst

[hugovk]

TODO: This was meant to be for the Python deprecations, not C API ones. I'll update it.

Updated.

[encukou]

Looks good to me, with one typo fix!

[ezio-melotti]

Would it make sense to add a new "Pending removal" section, with a paragraph describing what "pending removal" means, and include the other files as subsections?

These are currently nested under "New Deprecation" (not sure if intentionally):

I also noticed that there are two "Pending Removal in Python 3.x", for each "x", e.g.:

• https://cpython-previews--121241.org.readthedocs.build/en/121241/whatsnew/3.13.html#pending-removal-in-python-3-14
• https://cpython-previews--121241.org.readthedocs.build/en/121241/whatsnew/3.13.html#id7

Is this intentional?

[encukou]

I suggest not expanding the scope of the PR. Move the content in this one, rearrange the page later (and possibly only for 3.14).

I also noticed that there are two "Pending Removal in Python 3.x", for each "x", e.g.:

Yes, there are separate sections for Python API and C API, and they're not presented very clearly.

[ezio-melotti]

FWIW, I followed up on this in the original issue:

• Docs: move deprecations into include files #122085 (comment)

[miss-islington-app]

Thanks @hugovk for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13.
🐍🍒⛏🤖

[miss-islington-app]

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

cherry_picker a1df1b44394784721239615f307b273455536d14 3.13

[bedevere-app]

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

[hugovk]

I've opened #122085 as a tracking issue, and #122093 is the next PR.

[bedevere-app]

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

[bedevere-app]

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