bpo-43795: PEP 652 user documentation (GH-25668)

- Reformat the C API and ABI Versioning page (and extend/clarify a bit)
- Rewrite the stable ABI docs into a general text on C API Compatibility
- Add a list of Limited API contents, and notes for the individual items. 
- Replace `Include/README.rst` with a link to a devguide page with the same info

1 files changed, 5 insertions, 61 deletions

diff --git a/Include/README.rst b/Include/README.rst
index d2467ca..f52e690 100644
--- a/Include/README.rst
+++ b/Include/README.rst
@@ -3,66 +3,10 @@ The Python C API
 
 The C API is divided into three sections:
 
-1. ``Include/``
-2. ``Include/cpython/``
-3. ``Include/internal/``
+1. ``Include/``: Limited API
+2. ``Include/cpython/``: CPython implementation details
+3. ``Include/internal/``: The internal API
 
+Information on changing the C API is available `in the developer guide`_
 
-Include: Limited API
-====================
-
-``Include/``, excluding the ``cpython`` and ``internal`` subdirectories,
-contains the public Limited API (Application Programming Interface).
-The Limited API is a subset of the C API, designed to guarantee ABI
-stability across Python 3 versions, and is defined in :pep:`384`.
-
-Guidelines for expanding the Limited API:
-
-- Functions *must not* steal references
-- Functions *must not* return borrowed references
-- Functions returning references *must* return a strong reference
-- Macros should not expose implementation details
-- Please start a public discussion before expanding the API
-- Functions or macros with a ``_Py`` prefix do not belong in ``Include/``.
-
-It is possible to add a function or macro to the Limited API from a
-given Python version.  For example, to add a function to the Limited API
-from Python 3.10 and onwards, wrap it with
-``#if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030A0000``.
-
-
-Include/cpython: CPython implementation details
-===============================================
-
-``Include/cpython/`` contains the public API that is excluded from the
-Limited API and the Stable ABI.
-
-Guidelines for expanding the public API:
-
-- Functions *must not* steal references
-- Functions *must not* return borrowed references
-- Functions returning references *must* return a strong reference
-
-
-Include/internal: The internal API
-==================================
-
-
-With PyAPI_FUNC or PyAPI_DATA
------------------------------
-
-Functions or structures in ``Include/internal/`` defined with
-``PyAPI_FUNC`` or ``PyAPI_DATA`` are internal functions which are
-exposed only for specific use cases like debuggers and profilers.
-
-
-With the extern keyword
------------------------
-
-Functions in ``Include/internal/`` defined with the ``extern`` keyword
-*must not and can not* be used outside the CPython code base.  Only
-built-in stdlib extensions (built with the ``Py_BUILD_CORE_BUILTIN``
-macro defined) can use such functions.
-
-When in doubt, new internal C functions should be defined in
-``Include/internal`` using the ``extern`` keyword.
+.. _in the developer guide: https://devguide.python.org/c-api/