gh-95913: Prepare remaining Whatsnew sections for editing (#98342)

* Add line breaks & ref targets to Whatsnew to prepare for future changes

* Use standard heading underbar symbols for H4 sections

* Flatten Porting subsection; clarify scope of/link Python->CAPI sections

* Move C API pending deprecations to C API section, to match the others

1 files changed, 105 insertions, 28 deletions

diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst
index bb95383..d6ad79e 100644
--- a/Doc/whatsnew/3.11.rst
+++ b/Doc/whatsnew/3.11.rst
@@ -556,6 +556,8 @@ New Modules
   (Contributed by Sebastian Rittau in :issue:`42012`.)
 
 
+.. _whatsnew311-improved-modules:
+
 Improved Modules
 ================
 
@@ -1088,6 +1090,8 @@ fcntl
   the ``FD_CLOEXEC`` flag in addition.
 
 
+.. _whatsnew311-optimizations:
+
 Optimizations
 =============
 
@@ -1120,6 +1124,8 @@ Optimizations
   faster than Python 3.10.
 
 
+.. _whatsnew311-faster-cpython:
+
 Faster CPython
 ==============
 
@@ -1132,11 +1138,16 @@ could be up to 10-60% faster.
 This project focuses on two major areas in Python: faster startup and faster
 runtime. Other optimizations not under this project are listed in `Optimizations`_.
 
+
+.. _whatsnew311-faster-startup:
+
 Faster Startup
 --------------
 
+.. _whatsnew311-faster-imports:
+
 Frozen imports / Static code objects
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Python caches bytecode in the :ref:`__pycache__<tut-pycache>` directory to
 speed up module loading.
@@ -1161,11 +1172,16 @@ impact for short-running programs using Python.
 (Contributed by Eric Snow, Guido van Rossum and Kumar Aditya in numerous issues.)
 
 
+.. _whatsnew311-faster-runtime:
+
 Faster Runtime
 --------------
 
+.. _whatsnew311-lazy-python-frames:
+
 Cheaper, lazy Python frames
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 Python frames are created whenever Python calls a Python function. This frame
 holds execution information. The following are new frame optimizations:
 
@@ -1182,10 +1198,13 @@ up significantly. We measured a 3-7% speedup in pyperformance.
 
 (Contributed by Mark Shannon in :issue:`44590`.)
 
+
 .. _inline-calls:
+.. _whatsnew311-inline-calls:
 
 Inlined Python function calls
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 During a Python function call, Python will call an evaluating C function to
 interpret that function's code. This effectively limits pure Python recursion to
 what's safe for the C stack.
@@ -1202,8 +1221,12 @@ We measured a 1-3% improvement in pyperformance.
 
 (Contributed by Pablo Galindo and Mark Shannon in :issue:`45256`.)
 
+
+.. _whatsnew311-pep659:
+
 PEP 659: Specializing Adaptive Interpreter
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 :pep:`659` is one of the key parts of the faster CPython project. The general
 idea is that while Python is a dynamic language, most code has regions where
 objects and types rarely change. This concept is known as *type stability*.
@@ -1285,6 +1308,8 @@ Bucher, with additional help from Irit Katriel and Dennis Sweeney.)
        be sped up by :issue:`45947`.
 
 
+.. _whatsnew311-faster-cpython-misc:
+
 Misc
 ----
 
@@ -1296,6 +1321,9 @@ Misc
   time required for catching an exception by about 10%.
   (Contributed by Irit Katriel in :issue:`45711`.)
 
+
+.. _whatsnew311-faster-cpython-faq:
+
 FAQ
 ---
 
@@ -1330,6 +1358,8 @@ FAQ
 | A: No. We're still exploring other optimizations.
 
 
+.. _whatsnew311-faster-cpython-about:
+
 About
 -----
 
@@ -1339,6 +1369,8 @@ funded by Bloomberg LP to work on the project part-time. Finally, many
 contributors are volunteers from the community.
 
 
+.. _whatsnew311-bytecode-changes:
+
 CPython bytecode changes
 ========================
 
@@ -1395,9 +1427,17 @@ CPython bytecode changes
 * :opcode:`RESUME` has been added. It is a no-op. Performs internal tracing,
   debugging and optimization checks.
 
+
+.. _whatsnew311-deprecated:
+.. _whatsnew311-python-api-deprecated:
+
 Deprecated
 ==========
 
+This section lists Python APIs that have been deprecated in Python 3.11.
+
+Deprecated C APIs are :ref:`listed separately <whatsnew311-c-api-deprecated>`.
+
 * Chaining :class:`classmethod` descriptors (introduced in :issue:`19072`)
   is now deprecated.  It can no longer be used to wrap other descriptors
   such as :class:`property`.  The core design of this feature was flawed
@@ -1536,13 +1576,17 @@ Deprecated
   (Contributed by Serhiy Storchaka and Miro Hrončok in :gh:`92728`.)
 
 
+.. _whatsnew311-pending-removal:
+.. _whatsnew311-python-api-pending-removal:
+
 Pending Removal in Python 3.12
 ==============================
 
-The following APIs have been deprecated in earlier Python releases,
+The following Python APIs have been deprecated in earlier Python releases,
 and will be removed in Python 3.12.
 
-Python API:
+C APIs pending removal are
+:ref:`listed separately <whatsnew311-c-api-pending-removal>`.
 
 * :class:`pkgutil.ImpImporter`
 * :class:`pkgutil.ImpLoader`
@@ -1571,29 +1615,17 @@ Python API:
 * :func:`sqlite3.OptimizedUnicode`
 * :func:`sqlite3.enable_shared_cache`
 
-C API:
-
-* :c:func:`PyUnicode_AS_DATA`
-* :c:func:`PyUnicode_AS_UNICODE`
-* :c:func:`PyUnicode_AsUnicodeAndSize`
-* :c:func:`PyUnicode_AsUnicode`
-* :c:func:`PyUnicode_FromUnicode`
-* :c:func:`PyUnicode_GET_DATA_SIZE`
-* :c:func:`PyUnicode_GET_SIZE`
-* :c:func:`PyUnicode_GetSize`
-* :c:func:`PyUnicode_IS_COMPACT`
-* :c:func:`PyUnicode_IS_READY`
-* :c:func:`PyUnicode_READY`
-* :c:func:`Py_UNICODE_WSTR_LENGTH`
-* :c:func:`_PyUnicode_AsUnicode`
-* :c:macro:`PyUnicode_WCHAR_KIND`
-* :c:type:`PyUnicodeObject`
-* :c:func:`PyUnicode_InternImmortal()`
 
+.. _whatsnew311-removed:
+.. _whatsnew311-python-api-removed:
 
 Removed
 =======
 
+This section lists Python APIs that have been removed in Python 3.12.
+
+Removed C APIs are :ref:`listed separately <whatsnew311-c-api-removed>`.
+
 * :class:`smtpd.MailmanProxy` is now removed as it is unusable without
   an external module, ``mailman``. (Contributed by Dong-hee Na in :issue:`35800`.)
 
@@ -1686,15 +1718,18 @@ Removed
   of ``Tools/scripts`` and is `being developed independently
   <https://gitlab.com/warsaw/pynche/-/tree/main>`_ from the Python source tree.
 
+
+.. _whatsnew311-porting:
+.. _whatsnew311-python-api-porting:
+
 Porting to Python 3.11
 ======================
 
 This section lists previously described changes and other bugfixes
-that may require changes to your code.
+in the Python API that may require changes to your Python code.
 
-
-Changes in the Python API
--------------------------
+Porting notes for the C API are
+:ref:`listed separately <whatsnew311-c-api-porting>`.
 
 * Prohibited passing non-:class:`concurrent.futures.ThreadPoolExecutor`
   executors to :meth:`loop.set_default_executor` following a deprecation in
@@ -1743,6 +1778,9 @@ Changes in the Python API
   as meaningless when read. To get the pointer to the object's dictionary call
   :c:func:`PyObject_GenericGetDict` instead.
 
+
+.. _whatsnew311-build-changes:
+
 Build Changes
 =============
 
@@ -1830,9 +1868,13 @@ Build Changes
   (Contributed by Serhiy Storchaka in :issue:`46996`.)
 
 
+.. _whatsnew311-c-api:
+
 C API Changes
 =============
 
+.. _whatsnew311-c-api-new-features:
+
 New Features
 ------------
 
@@ -1896,6 +1938,9 @@ New Features
 * Added the :c:member:`PyConfig.safe_path` member.
   (Contributed by Victor Stinner in :gh:`57684`.)
 
+
+.. _whatsnew311-c-api-porting:
+
 Porting to Python 3.11
 ----------------------
 
@@ -2193,6 +2238,9 @@ Porting to Python 3.11
   paths and then modify them, finish initialization and use :c:func:`PySys_GetObject`
   to retrieve :data:`sys.path` as a Python list object and modify it directly.
 
+
+.. _whatsnew311-c-api-deprecated:
+
 Deprecated
 ----------
 
@@ -2218,6 +2266,35 @@ Deprecated
 * Deprecate the ``ob_shash`` member of the :c:type:`PyBytesObject`. Use :c:func:`PyObject_Hash` instead.
   (Contributed by Inada Naoki in :issue:`46864`.)
 
+
+.. _whatsnew311-c-api-pending-removal:
+
+Pending Removal in Python 3.12
+------------------------------
+
+The following C APIs have been deprecated in earlier Python releases,
+and will be removed in Python 3.12.
+
+* :c:func:`PyUnicode_AS_DATA`
+* :c:func:`PyUnicode_AS_UNICODE`
+* :c:func:`PyUnicode_AsUnicodeAndSize`
+* :c:func:`PyUnicode_AsUnicode`
+* :c:func:`PyUnicode_FromUnicode`
+* :c:func:`PyUnicode_GET_DATA_SIZE`
+* :c:func:`PyUnicode_GET_SIZE`
+* :c:func:`PyUnicode_GetSize`
+* :c:func:`PyUnicode_IS_COMPACT`
+* :c:func:`PyUnicode_IS_READY`
+* :c:func:`PyUnicode_READY`
+* :c:func:`Py_UNICODE_WSTR_LENGTH`
+* :c:func:`_PyUnicode_AsUnicode`
+* :c:macro:`PyUnicode_WCHAR_KIND`
+* :c:type:`PyUnicodeObject`
+* :c:func:`PyUnicode_InternImmortal()`
+
+
+.. _whatsnew311-c-api-removed:
+
 Removed
 -------