Close #15465: Document C API version macros

Mostly moving the existing macro docs over from the standard
library docs to the C API docs where they belong.

Patch by Kushal Das.

3 files changed, 51 insertions, 9 deletions

diff --git a/Doc/c-api/apiabiversion.rst b/Doc/c-api/apiabiversion.rst
new file mode 100644
index 0000000..f6d52df
--- /dev/null
+++ b/Doc/c-api/apiabiversion.rst
@@ -0,0 +1,39 @@
+.. highlightlang:: c
+
+.. _apiabiversion:
+
+***********************
+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``.
+
+All the given macros are defined in :source:`Include/patchlevel.h`.
+
diff --git a/Doc/c-api/index.rst b/Doc/c-api/index.rst
index 7b73e5b..591136e 100644
--- a/Doc/c-api/index.rst
+++ b/Doc/c-api/index.rst
@@ -23,3 +23,4 @@ document the API functions in detail.
    memory.rst
    objimpl.rst
    stable.rst
+   apiabiversion.rst
diff --git a/Doc/c-api/stable.rst b/Doc/c-api/stable.rst
index 2688c1c..a7c9ef9 100644
--- a/Doc/c-api/stable.rst
+++ b/Doc/c-api/stable.rst
@@ -2,9 +2,9 @@
 
 .. _stable:
 
-**********************************
-Stable Appliction Binary Interface
-**********************************
+***********************************
+Stable Application Binary Interface
+***********************************
 
 Traditionally, the C API of Python will change with every release.
 Most changes will be source-compatible, typically by only adding API,
@@ -23,13 +23,15 @@ need to be recompiled to link with a newer one.
 
 Since Python 3.2, a subset of the API has been declared to guarantee
 a stable ABI. Extension modules wishing to use this API need to define
-Py_LIMITED_API. A number of interpreter details then become hidden
+``Py_LIMITED_API``. A number of interpreter details then become hidden
 from the extension module; in return, a module is built that works
-on any 3.x version (x>=2) without recompilation. In some cases, the
-stable ABI needs to be extended with new functions. Extensions modules
-wishing to use these new APIs need to set Py_LIMITED_API to the
-PY_VERSION_HEX value of the minimum Python version they want to
-support (e.g. 0x03030000 for Python 3.3). Such modules will work
+on any 3.x version (x>=2) without recompilation.
+
+In some cases, the stable ABI needs to be extended with new functions.
+Extension modules wishing to use these new APIs need to set
+``Py_LIMITED_API`` to the ``PY_VERSION_HEX`` value (see
+:ref:`apiabiversion`) of the minimum Python version they want to
+support (e.g. ``0x03030000`` for Python 3.3). Such modules will work
 on all subsequent Python releases, but fail to load (because of
 missing symbols) on the older releases.