[3.11] gh-102304: Add links to the Stable ABI and Limited C API docs (#105345) (#105371) (#109901)

* Add "limited-c-api" and "stable-api" targets
* Rename the "stable-abi-list" target to "limited-api-list"

1 files changed, 31 insertions, 18 deletions

diff --git a/Doc/c-api/stable.rst b/Doc/c-api/stable.rst
index a697f6c..4817da4 100644
--- a/Doc/c-api/stable.rst
+++ b/Doc/c-api/stable.rst
@@ -25,19 +25,19 @@ are private API that can change without notice even in patch releases.
 Stable Application Binary Interface
 ===================================
 
+For simplicity, this document talks about *extensions*, but the Limited API
+and Stable ABI work the same way for all uses of the API – for example,
+embedding Python.
+
+.. _limited-c-api:
+
+Limited C API
+-------------
+
 Python 3.2 introduced the *Limited API*, a subset of Python's C API.
 Extensions that only use the Limited API can be
 compiled once and work with multiple versions of Python.
-Contents of the Limited API are :ref:`listed below <stable-abi-list>`.
-
-To enable this, Python provides a *Stable ABI*: a set of symbols that will
-remain compatible across Python 3.x versions. The Stable ABI contains symbols
-exposed in the Limited API, but also other ones – for example, functions
-necessary to support older versions of the Limited API.
-
-(For simplicity, this document talks about *extensions*, but the Limited API
-and Stable ABI work the same way for all uses of the API – for example,
-embedding Python.)
+Contents of the Limited API are :ref:`listed below <limited-api-list>`.
 
 .. c:macro:: Py_LIMITED_API
 
@@ -57,6 +57,19 @@ embedding Python.)
    You can also define ``Py_LIMITED_API`` to ``3``. This works the same as
    ``0x03020000`` (Python 3.2, the version that introduced Limited API).
 
+
+.. _stable-abi:
+
+Stable ABI
+----------
+
+To enable this, Python provides a *Stable ABI*: a set of symbols that will
+remain compatible across Python 3.x versions.
+
+The Stable ABI contains symbols exposed in the :ref:`Limited API
+<limited-c-api>`, but also other ones – for example, functions necessary to
+support older versions of the Limited API.
+
 On Windows, extensions that use the Stable ABI should be linked against
 ``python3.dll`` rather than a version-specific library such as
 ``python39.dll``.
@@ -101,9 +114,9 @@ Limited API Caveats
 -------------------
 
 Note that compiling with ``Py_LIMITED_API`` is *not* a complete guarantee that
-code conforms to the Limited API or the Stable ABI. ``Py_LIMITED_API`` only
-covers definitions, but an API also includes other issues, such as expected
-semantics.
+code conforms to the :ref:`Limited API <limited-c-api>` or the :ref:`Stable ABI
+<stable-abi>`. ``Py_LIMITED_API`` only covers definitions, but an API also
+includes other issues, such as expected semantics.
 
 One issue that ``Py_LIMITED_API`` does not guard against is calling a function
 with arguments that are invalid in a lower Python version.
@@ -136,9 +149,9 @@ Platform Considerations
 =======================
 
 ABI stability depends not only on Python, but also on the compiler used,
-lower-level libraries and compiler options. For the purposes of the Stable ABI,
-these details define a “platform”. They usually depend on the OS
-type and processor architecture
+lower-level libraries and compiler options. For the purposes of
+the :ref:`Stable ABI <stable-abi>`, these details define a “platform”. They
+usually depend on the OS type and processor architecture
 
 It is the responsibility of each particular distributor of Python
 to ensure that all Python versions on a particular platform are built
@@ -147,12 +160,12 @@ This is the case with Windows and macOS releases from ``python.org`` and many
 third-party distributors.
 
 
-.. _stable-abi-list:
+.. _limited-api-list:
 
 Contents of Limited API
 =======================
 
 
-Currently, the Limited API includes the following items:
+Currently, the :ref:`Limited API <limited-c-api>` includes the following items:
 
 .. limited-api-list::