From a01b4ad86f28d5871f968f407fe211a8f08bd331 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 11 Nov 2025 21:43:51 +0000
Subject: [PATCH 1/2] Fix DocC resource URLs on GitHub Pages

The issue was that commit 15dd75c removed the sed command that fixes
the baseURL in index.html. While --hosting-base-path tells DocC where
resources should be located, it doesn't always correctly set the baseURL
in the generated HTML. The baseURL is used by the JavaScript app to
construct paths to resources.

Without this fix, resources are loaded from:
  https://soundblaster.github.io/css/...
Instead of:
  https://soundblaster.github.io/NavigationSplitView/css/...

This commit:
- Restores --hosting-base-path NavigationSplitView (without leading slash)
- Adds back the sed command to fix "baseURL": "/" to "/NavigationSplitView/"
---
 .github/workflows/docc.yml | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/docc.yml b/.github/workflows/docc.yml
index 58ee986..005320e 100644
--- a/.github/workflows/docc.yml
+++ b/.github/workflows/docc.yml
@@ -45,9 +45,13 @@ jobs:
         run: |
           set -eo pipefail
           xcrun docc process-archive transform-for-static-hosting DocsArchive/NavigationSplitView.doccarchive \
-            --hosting-base-path /NavigationSplitView \
+            --hosting-base-path NavigationSplitView \
             --output-path DocsBuild
 
+          # Fix the baseURL in generated HTML
+          # DocC's --hosting-base-path doesn't always set baseURL correctly, so we fix it manually
+          sed -i '' 's|"baseURL": "/"|"baseURL": "/NavigationSplitView/"|g' DocsBuild/index.html
+
       - name: Upload documentation artifact
         if: github.event_name == 'push'
         uses: actions/upload-pages-artifact@v3

From 17a8a940cf3908e7358d80db07c89a05833a38c7 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 11 Nov 2025 21:47:49 +0000
Subject: [PATCH 2/2] Improve DocC workflow maintainability and robustness

Based on code review feedback, this commit addresses several
maintainability and robustness concerns:

1. **Environment variable for base path**
   - Added DOCC_HOSTING_BASE_PATH env var at workflow level
   - Makes it easy to change the base path in one place
   - Both --hosting-base-path and sed command now use this variable

2. **Better Xcode version management**
   - Replaced hardcoded sudo xcode-select with maxim-lobanov/setup-xcode@v1
   - More resilient to GitHub runner environment changes
   - Clearer intent and better error messages

3. **Explicit cleanup for reproducibility**
   - Added rm -rf DocsArchive DocsBuild before build
   - Ensures clean state for both CI and local testing
   - Prevents issues with stale artifacts

These changes improve the workflow from 8.5/10 to a more robust
and maintainable solution, addressing the main concerns about:
- Hard-coded paths that could break
- Difficulty in adapting to different base paths
- Reproducibility in different environments
---
 .github/workflows/docc.yml | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/docc.yml b/.github/workflows/docc.yml
index 005320e..983aa5c 100644
--- a/.github/workflows/docc.yml
+++ b/.github/workflows/docc.yml
@@ -15,6 +15,9 @@ concurrency:
   group: docc-pages
   cancel-in-progress: true
 
+env:
+  DOCC_HOSTING_BASE_PATH: NavigationSplitView
+
 jobs:
   build:
     name: Build DocC archive
@@ -24,8 +27,10 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
 
-      - name: Select Xcode 16.1 Developer Directory
-        run: sudo xcode-select -s /Applications/Xcode_16.1.app/Contents/Developer
+      - name: Select Xcode 16.1
+        uses: maxim-lobanov/setup-xcode@v1
+        with:
+          xcode-version: "16.1"
 
       - name: Show Xcode version
         run: xcodebuild -version
@@ -33,6 +38,8 @@ jobs:
       - name: Build documentation archive
         run: |
           set -eo pipefail
+          # Clean up any previous build artifacts
+          rm -rf DocsArchive DocsBuild
           mkdir -p DocsArchive
           xcrun docc convert XcodeProject/NewNav/Documentation.docc \
             --fallback-display-name "NavigationSplitView" \
@@ -45,12 +52,12 @@ jobs:
         run: |
           set -eo pipefail
           xcrun docc process-archive transform-for-static-hosting DocsArchive/NavigationSplitView.doccarchive \
-            --hosting-base-path NavigationSplitView \
+            --hosting-base-path "$DOCC_HOSTING_BASE_PATH" \
             --output-path DocsBuild
 
           # Fix the baseURL in generated HTML
           # DocC's --hosting-base-path doesn't always set baseURL correctly, so we fix it manually
-          sed -i '' 's|"baseURL": "/"|"baseURL": "/NavigationSplitView/"|g' DocsBuild/index.html
+          sed -i '' "s|\"baseURL\": \"/\"|\"baseURL\": \"/$DOCC_HOSTING_BASE_PATH/\"|g" DocsBuild/index.html
 
       - name: Upload documentation artifact
         if: github.event_name == 'push'