docs(cc): clarify abi_tag is equivalent to SOABI and cite PEP 3149 (bazel-contrib#3985)

Clarify the documentation for `abi_tag` in C++ Python toolchains so
that rule maintainers and users can easily map Bazel's toolchain
attributes to standard Python distribution environment variables.

Update docstrings in `python/private/py_cc_toolchain_info.bzl` and
`python/private/py_cc_toolchain_rule.bzl` to explicitly note that
`abi_tag` is the equivalent of the Python `sysconfig` variable `SOABI`,
accompanied by a reference citation to PEP 3149.

Also add `:::{versionadded} VERSION_NEXT_FEATURE` directives to all
newly
introduced toolchain fields and rule attributes.

Author: rickeylev

python/private/py_cc_toolchain_info.bzl

@@ -21,11 +21,19 @@ PyCcToolchainInfo = provider(
 :type: str
 
 The runtime's ABI flags, i.e. `sys.abiflags` (e.g. 't' for free-threaded builds).
+
+:::{versionadded} VERSION_NEXT_FEATURE
+:::
 """,
         "abi_tag": """\
 :type: str
 
-The ABI tag for extension modules, e.g. 'cpython-311' or 'cpython-313t'.
+The ABI tag for extension modules, equivalent to the `SOABI` sysconfig var
+(see [PEP 3149](https://peps.python.org/pep-3149/)), e.g. 'cpython-311' or
+'cpython-313t'.
+
+:::{versionadded} VERSION_NEXT_FEATURE
+:::
 """,
         "headers": """\
 :type: struct
@@ -107,12 +115,18 @@ If available, information about C libraries, struct with fields:
 
 The {pep}`PEP 508` `platform_machine` marker
 value for the target architecture, e.g. 'x86_64', 'aarch64'.
+
+:::{versionadded} VERSION_NEXT_FEATURE
+:::
 """,
         "platform_tag": """\
 :type: str | None
 
 The PEP 3149 / PEP 425 platform tag for extension modules, e.g.
 'x86_64-linux-gnu', 'darwin', or 'win_amd64'.
+
+:::{versionadded} VERSION_NEXT_FEATURE
+:::
 """,
         "python_version": """
 :type: str
@@ -124,6 +138,9 @@ The Python Major.Minor version.
 
 The {pep}`0508` `sys_platform` marker value
 for the target OS, e.g. 'linux', 'darwin', 'win32'.
+
+:::{versionadded} 2.2.0
+:::
 """,
     },
 )

python/private/py_cc_toolchain_rule.bzl

@@ -144,10 +144,20 @@ The runtime's ABI flags, i.e. `sys.abiflags`.
 If not set, or set to `<AUTO>`, the ABI flags are automatically derived
 from `--//python/config_settings:py_freethreaded` (e.g., `'t'` when
 free-threaded is enabled, or `''` otherwise).
+
+:::{versionadded} VERSION_NEXT_FEATURE
+:::
 """,
         ),
         "abi_tag": attr.string(
-            doc = "The ABI tag for extension modules, e.g. 'cpython-311'",
+            doc = """\
+The ABI tag for extension modules, equivalent to the `SOABI` sysconfig var
+(see [PEP 3149](https://peps.python.org/pep-3149/)), e.g. 'cpython-311' or
+'cpython-313t'.
+
+:::{versionadded} VERSION_NEXT_FEATURE
+:::
+""",
             default = "",
         ),
         "headers": attr.label(
@@ -171,7 +181,12 @@ attribute is available or not.
             providers = [[SentinelInfo], [CcInfo]],
         ),
         "libc": attr.string(
-            doc = "Target C library variant, e.g. 'glibc', 'musl'",
+            doc = """\
+Target C library variant, e.g. 'glibc', 'musl'.
+
+:::{versionadded} VERSION_NEXT_FEATURE
+:::
+""",
             default = "",
         ),
         "libs": attr.label(
@@ -182,6 +197,9 @@ attribute is available or not.
         "platform_machine": attr.string(
             doc = """
 Target architecture as a PEP 508 `platform_machine` marker, e.g. 'x86_64', 'aarch64', 'x86_32'.
+
+:::{versionadded} VERSION_NEXT_FEATURE
+:::
 """,
             default = "",
         ),
@@ -192,6 +210,9 @@ Target architecture as a PEP 508 `platform_machine` marker, e.g. 'x86_64', 'aarc
         "sys_platform": attr.string(
             doc = """
 Target OS as a PEP 508 `sys_platform` marker, e.g. 'linux', 'darwin', 'win32'.
+
+:::{versionadded} 2.2.0
+:::
 """,
             default = "",
         ),