[libc][docgen] simplify posix links

Usually posix functions have individual doc pages, and each header has its own
list of required macro definitions. Use a simpler key of "in-latest-posix" to
signal that the URL convention can be followed.

Add support for a "removed-in-posix-2008" key which will link to the 2004 docs
for functions like bcmp, bcopy, bzero, index, and rindex from strings.h.

Author: nickdesaulniers

libc/utils/docgen/docgen.py

@@ -52,8 +52,12 @@ def check_api(header: Header, api: Dict):
     :param api: docgen json file contents parsed into a dict
     """
     errors = []
-    cdef = "c-definition"
-    pdef = "posix-definition"
+    # We require entries to have at least one of these.
+    possible_keys = [
+        "c-definition",
+        "in-latest-posix",
+        "removed-in-posix-2008",
+    ]
 
     # Validate macros
     if "macros" in api:
@@ -66,8 +70,8 @@ def check_api(header: Header, api: Dict):
         macros = api["macros"]
 
         for name, obj in macros.items():
-            if not (cdef in obj or pdef in obj):
-                err = f'error: Macro {name} does not contain at least one required property: "{cdef}" or "{pdef}"'
+            if (not any(k in obj.keys() for k in possible_keys)):
+                err = f'error: Macro {name} does not contain at least one required property: {possible_keys}'
                 errors.append(err)
 
     # Validate functions
@@ -80,8 +84,8 @@ def check_api(header: Header, api: Dict):
 
         fns = api["functions"]
         for name, obj in fns.items():
-            if not (cdef in obj or pdef in obj):
-                err = f'error: function {name} does not contain at least one required property: "{cdef}" or "{pdef}"'
+          if (not any(k in obj.keys() for k in possible_keys)):
+                err = f'error: function {name} does not contain at least one required property: {possible_keys}'
                 errors.append(err)
 
     if errors:
@@ -104,7 +108,7 @@ def print_tbl_dir(name):
   * - {name}
     - Implemented
     - C23 Standard Section
-    - POSIX.1-2024 Standard Section"""
+    - POSIX Docs"""
     )
 
 
@@ -128,8 +132,10 @@ def print_functions_rst(header: Header, functions: Dict):
         else:
             print("    -")
 
-        if "posix-definition" in functions[name]:
-            print(f'    - {functions[name]["posix-definition"]}')
+        if "in-latest-posix" in functions[name]:
+            print(f'    - `POSIX.1-2024 <https://pubs.opengroup.org/onlinepubs/9799919799/functions/{name}.html>`__')
+        elif "removed-in-posix-2008" in functions[name]:
+            print(f'    - `removed in POSIX.1-2008 <https://pubs.opengroup.org/onlinepubs/007904875/functions/{name}.html>`__')
         else:
             print("    -")
 
@@ -154,8 +160,8 @@ def print_macros_rst(header: Header, macros: Dict):
         else:
             print("    -")
 
-        if "posix-definition" in macros[name]:
-            print(f'    - {macros[name]["posix-definition"]}')
+        if "in-latest-posix" in macros[name]:
+            print(f'    - `POSIX.1-2024 <https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/{header.name}.html>`__')
         else:
             print("    -")
     print()