Docs: move deprecations into include files

[hugovk]

Documentation

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

To avoid needing to duplicate and sync the deprecation sections across What's New files, and ease backports, move them into include files.

• Python:
  • Use include files for whatsnew/3.12.rst deprecations
  • Use include files for whatsnew/3.13.rst deprecations
  • Use include files for whatsnew/3.14.rst deprecations
• C API:
  • Use include files for deprecations
• Create dedicated page to list deprecations using include files

Linked PRs

• gh-122085: Use include files for whatsnew/3.13.rst deprecations #121241
• [3.13] gh-122085: Use include files for whatsnew/3.13.rst deprecations (GH-121241) #122038
• gh-122085: Use include files for whatsnew/3.12.rst deprecations #122093
• [3.13] gh-122085: Use include files for whatsnew/3.12.rst deprecations (GH-122093) #122223
• [3.13] gh-122085: Use include files for whatsnew/3.12.rst deprecations, including 3.16 (GH-122093) #122225
• [3.12] gh-122085: Use include files for whatsnew/3.12.rst deprecations (GH-122093) #122224
• gh-122085: Use include files for whatsnew/3.14.rst deprecations #122242
• [3.13] gh-122085: Use include files for whatsnew/3.14.rst deprecations (GH-122242) #122350
• [3.12] gh-122085: Use include files for whatsnew/3.14.rst deprecations (GH-122242) #122351
• gh-122085: Use include files for C API deprecations #109843
• gh-122085: Create dedicated page for deprecations #122352
• [3.13] gh-122085: Create dedicated page for deprecations (GH-122352) #122374
• [3.12] gh-122085: Create dedicated page for deprecations (GH-122352) #122375
• [3.13] GH-122085: Use include files for C API deprecations (GH-109843) #122422
• [3.12] GH-122085: Use include files for C API deprecations (GH-109843) #122423

[AA-Turner]

Anything left outstanding?

A

[hugovk]

@ezio-melotti and @encukou discussed some rearrangements in #121241 (comment), now is a good time for that. What did you have in mind?

[ezio-melotti]

What did you have in mind?

I'm looking at the ToC of What's new in 3.13, which looks like:

...
Optimizations
Removed Modules And APIs
    ...
New Deprecations
    Pending Removal in Python 3.14
    Pending Removal in Python 3.15
    Pending Removal in Python 3.16
    Pending Removal in Future Versions
CPython Bytecode Changes
C API Changes
    New Features
Build Changes
Porting to Python 3.13
    Changes in the Python API
    Changes in the C API
    Removed C APIs
    Deprecated C APIs
    Pending Removal in Python 3.14
    Pending Removal in Python 3.15
    Pending Removal in Future Versions
Regression Test Changes
...

There are a few issues here:

1. The "Pending Removal"s don't seem to belong under "New Deprecations", assuming they also include existing deprecations carried over from previous versions.
2. It also seems that some (all?) new deprecations are also duplicated under the "Pending Removal"s.
3. All these sections except "Pending Removal in Future Versions" have no introductory paragraph to explain briefly what are they listing (possibly including the fact that some entries are duplicated and that old deprecations are included too).
4. Under "Porting to Python 3.13" there's another set of "Pending Removal"s, with no clear indication of the difference with the previous set. Since the title is the same, it creates a conflict in the link fragment (and the fragment is replaced by an #idxx)
5. This part also doesn't mirror the previous one, with "Deprecated C APIs" seemingly being the C equivalent of the previous "New Deprecations", even though it's now on the same level.
6. This new set of "Pending Removal"s seems to be about C APIs, but this is not clear from the title, and it's also not explicitly mentioned in the sections themselves.
7. The "Porting to Python 3.13" section should arguably also contains the first set of "Pending Removal"s, or maybe both sets should be moved before and referenced where needed.
8. "Pending Removal in Python 3.16" is missing from the second set (maybe intentionally if there are no new deprecations? should it still be added with a short note stating that there are currently no deprecations about features removed in 3.16?)

Taking a step back, we might want to separate both Python changes from C changes (this applies to rest too) or new vs existing deprecations (this only applies to deprecation), i.e.:

Python changes
  New APIs
  Deprecations
     New Deprecations
     Pending removal in 3.x
     Pending removal in future versions
C changes
  New APIs
  Deprecations
     New Deprecations
     Pending removal in 3.x
     Pending removal in future versions

or

...
New APIs
  Python APIs
  C APIs
Deprecations
  New Deprecations
    Python Deprecations
    C Deprecations
  Pending removal in 3.x
    Python
    C
  ...
  Pending removal in future versions
    Python
    C

IOW, either the structure of the document is confusing (and should be fixed), or I am misunderstanding it (which probably means that it's confusing (and should be fixed)).