fix(ci): replace yq with Python nav patching in publish-devnotes (#548)

The yq JSON roundtrip was mangling the entire mkdocs.yml file
(indentation, quoting, comments), causing mike deploy to fail.

Extract a Python script that surgically replaces only the Dev Notes
nav block, leaving all other content byte-identical.

Author: andreatgretel

.github/scripts/patch-devnotes-nav.py

@@ -0,0 +1,57 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Patch the Dev Notes nav block in mkdocs.yml.
+
+Used by publish-devnotes.yml to splice HEAD's Dev Notes nav entries into an
+older source checkout without touching the rest of the file.
+
+Usage: python patch-devnotes-nav.py <head_mkdocs> <target_mkdocs>
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+
+
+def extract_devnotes_block(text: str) -> tuple[int, int, list[str]]:
+    """Return (start, end, lines) for the '  - Dev Notes:' nav block."""
+    lines = text.splitlines(keepends=True)
+    start = None
+    for i, line in enumerate(lines):
+        if re.match(r"^  - Dev Notes:", line):
+            start = i
+            break
+    if start is None:
+        raise SystemExit("Dev Notes nav section not found")
+    end = start + 1
+    while end < len(lines):
+        # Stop at next top-level nav entry (2-space indent) or non-nav section
+        if lines[end].strip() and not lines[end].startswith("      ") and not lines[end].startswith("      #"):
+            break
+        end += 1
+    return start, end, lines
+
+
+def main() -> None:
+    if len(sys.argv) != 3:
+        raise SystemExit(f"Usage: {sys.argv[0]} <head_mkdocs> <target_mkdocs>")
+
+    head_path, target_path = sys.argv[1], sys.argv[2]
+
+    with open(head_path) as f:
+        head_start, head_end, head_lines = extract_devnotes_block(f.read())
+    head_block = head_lines[head_start:head_end]
+
+    with open(target_path) as f:
+        old_start, old_end, old_lines = extract_devnotes_block(f.read())
+    new_lines = old_lines[:old_start] + head_block + old_lines[old_end:]
+
+    with open(target_path, "w") as f:
+        f.writelines(new_lines)
+    print(f"Patched Dev Notes nav: replaced lines {old_start + 1}-{old_end} with {len(head_block)} lines from HEAD")
+
+
+if __name__ == "__main__":
+    main()

.github/workflows/publish-devnotes.yml

@@ -38,16 +38,14 @@ jobs:
       - name: Checkout docs source and overlay devnotes
         run: |
           git checkout ${{ env.SOURCE_SHA }}
-          git checkout ${{ github.sha }} -- docs/devnotes/
+          git checkout ${{ github.sha }} -- docs/devnotes/ .github/scripts/patch-devnotes-nav.py
 
           # Patch the "Dev Notes" nav section from HEAD's mkdocs.yml into the
           # old source's mkdocs.yml. This keeps nav entries for new devnotes
           # without pulling in entries for non-devnotes pages that may not
           # exist in the old source checkout.
-          pip install -q yq
-          DEVNOTES_NAV=$(git show ${{ github.sha }}:mkdocs.yml \
-            | yq '.nav[] | select(has("Dev Notes")) | .["Dev Notes"]')
-          yq -y -i "(.nav[] | select(has(\"Dev Notes\")))[\"Dev Notes\"] = ${DEVNOTES_NAV}" mkdocs.yml
+          git show ${{ github.sha }}:mkdocs.yml > /tmp/mkdocs-head.yml
+          python3 .github/scripts/patch-devnotes-nav.py /tmp/mkdocs-head.yml mkdocs.yml
       - name: Install uv
         uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
         with: