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, 52 insertions, 29 deletions

diff --git a/Doc/c-api/apiabiversion.rst b/Doc/c-api/apiabiversion.rst
index b8a8f2f..04050f7 100644
--- a/Doc/c-api/apiabiversion.rst
+++ b/Doc/c-api/apiabiversion.rst
@@ -6,34 +6,57 @@
 API and ABI Versioning
 ***********************
 
-``PY_VERSION_HEX`` is the Python version number encoded in a single integer.
-
-For example if the ``PY_VERSION_HEX`` is set to ``0x030401a2``, the underlying
-version information can be found by treating it as a 32 bit number in
-the following manner:
-
-   +-------+-------------------------+------------------------------------------------+
-   | Bytes | Bits (big endian order) | Meaning                                        |
-   +=======+=========================+================================================+
-   | ``1`` |       ``1-8``           |  ``PY_MAJOR_VERSION`` (the ``3`` in            |
-   |       |                         |  ``3.4.1a2``)                                  |
-   +-------+-------------------------+------------------------------------------------+
-   | ``2`` |       ``9-16``          |  ``PY_MINOR_VERSION`` (the ``4`` in            |
-   |       |                         |  ``3.4.1a2``)                                  |
-   +-------+-------------------------+------------------------------------------------+
-   | ``3`` |       ``17-24``         |  ``PY_MICRO_VERSION`` (the ``1`` in            |
-   |       |                         |  ``3.4.1a2``)                                  |
-   +-------+-------------------------+------------------------------------------------+
-   | ``4`` |       ``25-28``         |  ``PY_RELEASE_LEVEL`` (``0xA`` for alpha,      |
-   |       |                         |  ``0xB`` for beta, ``0xC`` for release         |
-   |       |                         |  candidate and ``0xF`` for final), in this     |
-   |       |                         |  case it is alpha.                             |
-   +-------+-------------------------+------------------------------------------------+
-   |       |       ``29-32``         |  ``PY_RELEASE_SERIAL`` (the ``2`` in           |
-   |       |                         |  ``3.4.1a2``, zero for final releases)         |
-   +-------+-------------------------+------------------------------------------------+
-
-Thus ``3.4.1a2`` is hexversion ``0x030401a2``.
+CPython exposes its version number in the following macros.
+Note that these correspond to the version code is **built** with,
+not necessarily the version used at **run time**.
 
-All the given macros are defined in :source:`Include/patchlevel.h`.
+See :ref:`stable` for a discussion of API and ABI stability across versions.
+
+.. c:macro:: PY_MAJOR_VERSION
+
+   The ``3`` in ``3.4.1a2``.
+
+.. c:macro:: PY_MINOR_VERSION
+
+   The ``4`` in ``3.4.1a2``.
+
+.. c:macro:: PY_MICRO_VERSION
+
+   The ``1`` in ``3.4.1a2``.
+
+.. c:macro:: PY_RELEASE_LEVEL
+
+   The ``a`` in ``3.4.1a2``.
+   This can be ``0xA`` for alpha, ``0xB`` for beta, ``0xC`` for release
+   candidate or ``0xF`` for final.
 
+.. c:macro:: PY_RELEASE_SERIAL
+
+   The ``2`` in ``3.4.1a2``. Zero for final releases.
+
+.. c:macro:: PY_VERSION_HEX
+
+   The Python version number encoded in a single integer.
+
+   The underlying version information can be found by treating it as a 32 bit
+   number in the following manner:
+
+   +-------+-------------------------+-------------------------+--------------------------+
+   | Bytes | Bits (big endian order) | Meaning                 | Value for ``3.4.1a2``    |
+   +=======+=========================+=========================+==========================+
+   |   1   |         1-8             |  ``PY_MAJOR_VERSION``   | ``0x03``                 |
+   +-------+-------------------------+-------------------------+--------------------------+
+   |   2   |         9-16            |  ``PY_MINOR_VERSION``   | ``0x04``                 |
+   +-------+-------------------------+-------------------------+--------------------------+
+   |   3   |         17-24           |  ``PY_MICRO_VERSION``   | ``0x01``                 |
+   +-------+-------------------------+-------------------------+--------------------------+
+   |   4   |         25-28           |  ``PY_RELEASE_LEVEL``   | ``0xA``                  |
+   +       +-------------------------+-------------------------+--------------------------+
+   |       |         29-32           |  ``PY_RELEASE_SERIAL``  | ``0x2``                  |
+   +-------+-------------------------+-------------------------+--------------------------+
+
+   Thus ``3.4.1a2`` is hexversion ``0x030401a2`` and ``3.10.0`` is
+   hexversion ``0x030a00f0``.
+
+
+All the given macros are defined in :source:`Include/patchlevel.h`.