From 105544b4bc9267fd0f96a08ae9f3563893430512 Mon Sep 17 00:00:00 2001
From: Alex Reinking <areinking@adobe.com>
Date: Wed, 19 Aug 2026 16:10:17 -0400
Subject: [PATCH] Fix deploy-docs.yml API reference generation on CI

The Doxygen XML for an anonymous enum's <name> is an empty element on
Doxygen 1.9.8 (Ubuntu 24.04's apt package) but a synthetic "@N" string
on newer releases; generate_api_reference.py only handled the latter,
crashing with TypeError on CI while working fine locally against a
newer local Doxygen. Handle both, and also install upstream's official
1.18.0 binary in the workflow so CI isn't stuck on the ancient
distro-packaged version going forward.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .github/workflows/deploy-docs.yml | 18 +++++++++++++++++-
 doc/generate_api_reference.py     |  5 ++++-
 2 files changed, 21 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
index e8d3f5c063c1..09fc660fdbd0 100644
--- a/.github/workflows/deploy-docs.yml
+++ b/.github/workflows/deploy-docs.yml
@@ -43,7 +43,23 @@ jobs:
       - name: Install system dependencies
         run: |
           sudo apt-get update
-          sudo apt-get install -y libpng-dev libjpeg-dev doxygen gdb
+          sudo apt-get install -y libpng-dev libjpeg-dev gdb
+
+      - name: Install Doxygen
+        env:
+          DOXYGEN_VERSION: 1.18.0
+          DOXYGEN_SHA256: 14fa81bdc34171edb5f1f02b1d60e74802f0439b77fa44e592565d517d72df90
+        run: |
+          # Ubuntu 24.04's apt package is stuck on Doxygen 1.9.8, which
+          # emits an empty <name/> for anonymous enums instead of a
+          # synthetic "@N" name -- generate_api_reference.py only handles
+          # the latter. Install upstream's official prebuilt binary
+          # instead of waiting on the distro package to catch up.
+          curl -fsSL -o doxygen.tar.gz \
+            "https://github.com/doxygen/doxygen/releases/download/Release_${DOXYGEN_VERSION//./_}/doxygen-${DOXYGEN_VERSION}.linux.bin.tar.gz"
+          echo "${DOXYGEN_SHA256}  doxygen.tar.gz" | sha256sum -c -
+          tar xzf doxygen.tar.gz
+          echo "${GITHUB_WORKSPACE}/doxygen-${DOXYGEN_VERSION}/bin" >> "$GITHUB_PATH"
 
       - name: Sync CI environment
         run: |
diff --git a/doc/generate_api_reference.py b/doc/generate_api_reference.py
index dcc815f27111..f482580c8de0 100755
--- a/doc/generate_api_reference.py
+++ b/doc/generate_api_reference.py
@@ -158,7 +158,10 @@ def _member_names(xml_dir: Path, container_refid: str, member_kinds, name_prefix
             continue
         for memberdef in sectiondef.findall("memberdef"):
             name = memberdef.find("name").text
-            if "@" in name:
+            # Anonymous enums get a synthetic "@N" name on newer Doxygen, but
+            # an empty <name/> (None here) on older ones (e.g. 1.9.8) -- both
+            # mean the same "no real name" thing and should be skipped.
+            if not name or "@" in name:
                 continue
             location = memberdef.find("location")
             file = location.get("file") if location is not None else "unknown"