Merge remote-tracking branch 'upstream/master' into feature/io

Author: danrbailey

.github/workflows/build.yml

@@ -19,6 +19,8 @@ on:
       - 'pendingchanges/**'
       - '**.md'
   pull_request:
+    # Add 'ready_for_review' to run CI when a draft PR is marked ready.
+    types: [opened, synchronize, reopened, ready_for_review]
     branches:
       - '**'
     paths-ignore:
@@ -53,9 +55,10 @@ jobs:
     # VFX platform jobs. These are run on the appropriate CentOS images from
     # the provided ASWF docker containers
     if: |
-      github.event_name != 'workflow_dispatch' ||
-      github.event.inputs.type == 'all' ||
-      github.event.inputs.type == 'linux'
+      (github.event_name == 'push' ||
+       (github.event_name == 'pull_request' && github.event.pull_request.draft == false) ||
+       (github.event_name == 'workflow_dispatch' &&
+        (github.event.inputs.type == 'all' || github.event.inputs.type == 'linux')))
     runs-on: ${{ (github.repository_owner == 'AcademySoftwareFoundation' && 'ubuntu-22.04-8c-32g-300h') || 'ubuntu-latest' }}
     name: >
       linux:${{ matrix.config.image }}-abi:${{ matrix.config.abi }}-cxx:${{ matrix.config.cxx }}-type:${{ matrix.config.build }}
@@ -119,9 +122,10 @@ jobs:
   windows:
     # Windows CI. Tests a dynamic build with MD.
     if: |
-      github.event_name != 'workflow_dispatch' ||
-      github.event.inputs.type == 'all' ||
-      github.event.inputs.type == 'win'
+      (github.event_name == 'push' ||
+       (github.event_name == 'pull_request' && github.event.pull_request.draft == false) ||
+       (github.event_name == 'workflow_dispatch' &&
+        (github.event.inputs.type == 'all' || github.event.inputs.type == 'win')))
     runs-on: ${{ (github.repository_owner == 'AcademySoftwareFoundation' && 'windows-2022-8c-32g-300h') || 'windows-latest' }}
     name: windows
     env:
@@ -163,9 +167,10 @@ jobs:
 
   macos:
     if: |
-      github.event_name != 'workflow_dispatch' ||
-      github.event.inputs.type == 'all' ||
-      github.event.inputs.type == 'mac'
+      (github.event_name == 'push' ||
+       (github.event_name == 'pull_request' && github.event.pull_request.draft == false) ||
+       (github.event_name == 'workflow_dispatch' &&
+        (github.event.inputs.type == 'all' || github.event.inputs.type == 'mac')))
     runs-on: ${{ matrix.config.image }}
     name: ${{ matrix.config.image }}
     env:

.github/workflows/docs.yml

@@ -11,15 +11,13 @@ on:
       - 'CHANGES'
       - 'openvdb_maya/**'
       - 'pendingchanges/**'
-      - '**.md'
   pull_request:
     branches:
       - '**'
     paths-ignore:
       - 'CHANGES'
       - 'openvdb_maya/**'
       - 'pendingchanges/**'
-      - '**.md'
   workflow_dispatch:
     inputs:
       deploy:
@@ -33,7 +31,24 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  validate_docs:
+    # Cheap static checks that run before the heavier doxygen build:
+    #  * every #include <...> referenced from a fenced code block in doc/ resolves
+    #  * every github.com/.../blob/<branch>/<path> URL points to a file on disk
+    # Catches the class of docs-rot from issue #2161 (e.g. nanovdb::util ->
+    # nanovdb::tools rename) before the doxygen job runs.
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - name: set_up_python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.x'
+    - name: run_validator
+      run: python3 ci/validate_docs_references.py
+
   doxygen:
+    needs: validate_docs
     runs-on: ${{ (github.repository_owner == 'AcademySoftwareFoundation' && 'ubuntu-22.04-8c-32g-300h') || 'ubuntu-latest' }}
     env:
       CXX: g++
@@ -45,9 +60,12 @@ jobs:
       run: ./ci/install_doxygen.sh 1_14_0
     - name: nanobind
       run: ./ci/install_nanobind.sh 2.5.0
-    - name: install_latex
-      run: ./ci/install_texlive.sh
     - name: build
+      # Doxygen's native WARN_AS_ERROR=FAIL_ON_WARNINGS gates the docs build:
+      # any warning fails the job. FAIL_ON_WARNINGS still generates the docs and
+      # writes the full warning log first, so the artifact step below captures
+      # it for debugging. Enabled via OPENVDB_DOXYGEN_WARN_AS_ERROR (see
+      # doc/CMakeLists.txt).
       run: >
         ./ci/build.sh -v
         --build-type=Release
@@ -58,7 +76,18 @@ jobs:
         -DOPENVDB_PYTHON_WRAP_ALL_GRID_TYPES=ON
         -DUSE_EXPLICIT_INSTANTIATION=OFF
         -DDISABLE_DEPENDENCY_VERSION_CHECKS=ON
+        -DOPENVDB_DOXYGEN_WARN_AS_ERROR=ON
         \"
+    - name: upload_doxygen_warning_log
+      # Always upload so contributors can debug failed PR builds without
+      # having to reproduce the doxygen environment locally.
+      if: always()
+      uses: actions/upload-artifact@v4
+      with:
+        name: doxygen-warnings
+        path: build/doc/doxygen.warnings.log
+        if-no-files-found: ignore
+        retention-days: 14
     - name: pre_deploy
       # Overwrite global SSH configuration
       #  https://github.com/peaceiris/actions-gh-pages/issues/719
@@ -147,4 +176,3 @@ jobs:
           - Deployed from: AcademySoftwareFoundation/openvdb ${{ github.sha }}
 
           Signed-off-by: ${{ github.actor }} <${{ github.actor }}@users.noreply.github.com>"
-

.github/workflows/nanovdb.yml

@@ -18,6 +18,8 @@ on:
       - 'pendingchanges/**'
       - '**.md'
   pull_request:
+    # Add 'ready_for_review' to run CI when a draft PR is marked ready.
+    types: [opened, synchronize, reopened, ready_for_review]
     branches:
       - '**'
     paths-ignore:
@@ -44,10 +46,12 @@ concurrency:
 
 jobs:
   linux-nanovdb:
+    # push OR non-draft PR OR matching manual run
     if: |
-      github.event_name != 'workflow_dispatch' ||
-      github.event.inputs.type == 'all' ||
-      github.event.inputs.type == 'linux'
+      (github.event_name == 'push' ||
+       (github.event_name == 'pull_request' && github.event.pull_request.draft == false) ||
+       (github.event_name == 'workflow_dispatch' &&
+        (github.event.inputs.type == 'all' || github.event.inputs.type == 'linux')))
     runs-on: ${{ (github.repository_owner == 'AcademySoftwareFoundation' && 'ubuntu-22.04-8c-32g-300h') || 'ubuntu-latest' }}
     name: >
       linux-nanovdb:cxx:${{ matrix.config.cxx }}-${{ matrix.config.build }}
@@ -92,9 +96,10 @@ jobs:
 
   windows-nanovdb:
     if: |
-      github.event_name != 'workflow_dispatch' ||
-      github.event.inputs.type == 'all' ||
-      github.event.inputs.type == 'win'
+      (github.event_name == 'push' ||
+       (github.event_name == 'pull_request' && github.event.pull_request.draft == false) ||
+       (github.event_name == 'workflow_dispatch' &&
+        (github.event.inputs.type == 'all' || github.event.inputs.type == 'win')))
     runs-on: ${{ (github.repository_owner == 'AcademySoftwareFoundation' && 'windows-2022-8c-32g-300h') || 'windows-latest' }}
     env:
       VCPKG_DEFAULT_TRIPLET: 'x64-windows'
@@ -139,9 +144,10 @@ jobs:
 
   macos-nanovdb:
     if: |
-      github.event_name != 'workflow_dispatch' ||
-      github.event.inputs.type == 'all' ||
-      github.event.inputs.type == 'mac'
+      (github.event_name == 'push' ||
+       (github.event_name == 'pull_request' && github.event.pull_request.draft == false) ||
+       (github.event_name == 'workflow_dispatch' &&
+        (github.event.inputs.type == 'all' || github.event.inputs.type == 'mac')))
     runs-on: ${{ matrix.config.runner }}
     env:
       CXX: ${{ matrix.config.cxx }}
@@ -168,9 +174,10 @@ jobs:
 
   nanovdb-lite:
     if: |
-      github.event_name != 'workflow_dispatch' ||
-      github.event.inputs.type == 'all' ||
-      github.event.inputs.type == 'linux'
+      (github.event_name == 'push' ||
+       (github.event_name == 'pull_request' && github.event.pull_request.draft == false) ||
+       (github.event_name == 'workflow_dispatch' &&
+        (github.event.inputs.type == 'all' || github.event.inputs.type == 'linux')))
     runs-on: ${{ (github.repository_owner == 'AcademySoftwareFoundation' && 'ubuntu-22.04-8c-32g-300h') || 'ubuntu-latest' }}
     container:
       image: aswf/ci-openvdb:2024-clang17.2