[libc-commits] [libc] [libc][docs] Fix POSIX basedefs links for nested headers (PR #188738)

[Petter Berntsson via libc-commits]

https://github.com/petbernt created https://github.com/llvm/llvm-project/pull/188738

Fix broken POSIX basedefs links for nested headers in llvm-libc docs.

The docgen script currently emits paths like `sys/wait.h.html`, but the Open Group uses `sys_wait.h.html`, for example:
  - https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/sys_wait.h.html

This updates nested-header link generation while leaving flat headers unchanged.

>From b92cf49f93e780c87453bb213eda6d7eeef851dd Mon Sep 17 00:00:00 2001
From: Petter Berntsson <petter.berntsson at arm.com>
Date: Thu, 26 Mar 2026 12:35:01 +0000
Subject: [PATCH] [libc][docs] Fix POSIX basedefs links for nested headers

The Open Group publishes basedefs pages for nested headers by
replacing '/' with '_'. Use that filename form when generating
macro links so headers like sys/wait.h point to a valid page.
---
 libc/utils/docgen/docgen.py | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/libc/utils/docgen/docgen.py b/libc/utils/docgen/docgen.py
index 59cfbd54561c7..a2296dcab1a32 100755
--- a/libc/utils/docgen/docgen.py
+++ b/libc/utils/docgen/docgen.py
@@ -149,6 +149,11 @@ def print_functions_rst(header: Header, functions: Dict):
             print("    -")
 
 
+def posix_header_name(header: Header) -> str:
+    """Map nested header names to the Open Group basedefs filename form."""
+    return header.name.replace("/", "_")
+
+
 def print_macros_rst(header: Header, macros: Dict):
     tbl_hdr = "Macros"
     print(tbl_hdr)
@@ -171,7 +176,7 @@ def print_macros_rst(header: Header, macros: Dict):
 
         if "in-latest-posix" in macros[name]:
             print(
-                f"    - `POSIX.1-2024 <https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/{header.name}.html>`__"
+                f"    - `POSIX.1-2024 <https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/{posix_header_name(header)}.html>`__"
             )
         else:
             print("    -")