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, 27 insertions, 6 deletions

diff --git a/Tools/scripts/stable_abi.py b/Tools/scripts/stable_abi.py
index 399153d..2ba5b66 100755
--- a/Tools/scripts/stable_abi.py
+++ b/Tools/scripts/stable_abi.py
@@ -21,6 +21,7 @@ import os
 import os.path
 import io
 import re
+import csv
 
 MISSING = object()
 
@@ -45,6 +46,11 @@ EXCLUDED_HEADERS = {
 MACOS = (sys.platform == "darwin")
 UNIXY = MACOS or (sys.platform == "linux")  # XXX should this be "not Windows"?
 
+IFDEF_DOC_NOTES = {
+    'MS_WINDOWS': 'on Windows',
+    'HAVE_FORK': 'on platforms with fork()',
+    'USE_STACKCHECK': 'on platforms with USE_STACKCHECK',
+}
 
 # The stable ABI manifest (Misc/stable_abi.txt) exists only to fill the
 # following dataclasses.
@@ -227,16 +233,31 @@ def gen_python3dll(manifest, args, outfile):
             key=sort_key):
         write(f'EXPORT_DATA({item.name})')
 
+REST_ROLES = {
+    'function': 'function',
+    'data': 'var',
+    'struct': 'type',
+    'macro': 'macro',
+    # 'const': 'const',  # all undocumented
+    'typedef': 'type',
+}
 
 @generator("doc_list", 'Doc/data/stable_abi.dat')
 def gen_doc_annotations(manifest, args, outfile):
     """Generate/check the stable ABI list for documentation annotations"""
-    write = partial(print, file=outfile)
-    write("# Generated by Tools/scripts/stable_abi.py")
-    write()
-    for item in manifest.select(ABIItem.KINDS, include_abi_only=False):
-        write(item.name)
-
+    writer = csv.DictWriter(
+        outfile, ['role', 'name', 'added', 'ifdef_note'], lineterminator='\n')
+    writer.writeheader()
+    for item in manifest.select(REST_ROLES.keys(), include_abi_only=False):
+        if item.ifdef:
+            ifdef_note = IFDEF_DOC_NOTES[item.ifdef]
+        else:
+            ifdef_note = None
+        writer.writerow({
+            'role': REST_ROLES[item.kind],
+            'name': item.name,
+            'added': item.added,
+            'ifdef_note': ifdef_note})
 
 def generate_or_check(manifest, args, path, func):
     """Generate/check a file with a single generator