docs.yml

name: Docs

on:
  push:
    branches:
      - 'master'
      - 'feature/**'
      - 'pr/**'
    paths-ignore:
      - 'CHANGES'
      - 'openvdb_maya/**'
      - 'pendingchanges/**'
  pull_request:
    branches:
      - '**'
    paths-ignore:
      - 'CHANGES'
      - 'openvdb_maya/**'
      - 'pendingchanges/**'
  workflow_dispatch:
    inputs:
      deploy:
        description: 'Deploy to openvdb-website (docs/coverage)?'
        required: true
        default: 'none'

# Allow subsequent pushes to the same PR or REF to cancel any previous jobs.
concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  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++
    container:
      image: aswf/ci-openvdb:2026
    steps:
    - uses: actions/checkout@v4
    - name: install_doxygen
      run: ./ci/install_doxygen.sh 1_14_0
    - name: nanobind
      run: ./ci/install_nanobind.sh 2.5.0
    - 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
        --components="core,python,doc"
        --cargs=\"
        -DUSE_BLOSC=OFF
        -DOPENVDB_CORE_STATIC=OFF
        -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
      #  https://linuxhint.com/ssh-stricthostkeychecking/
      run: >
        echo "Host *
          StrictHostKeyChecking no
          UserKnownHostsFile=/dev/null
        " > /etc/ssh/ssh_config
    - name: deploy
      # only deploy documentation on a manual workflow dispatch
      if: |
        github.repository_owner == 'AcademySoftwareFoundation' &&
        github.event_name == 'workflow_dispatch' &&
        github.event.inputs.deploy == 'docs'
      uses: peaceiris/actions-gh-pages@v3
      with:
        deploy_key: ${{ secrets.PRIVATE_KEY }}
        publish_dir: /usr/local/share/doc/OpenVDB/html
        destination_dir: documentation/doxygen
        external_repository: AcademySoftwareFoundation/openvdb-website
        publish_branch: master
        full_commit_message: "Automatic doxygen documentation update
          - Deployed from: AcademySoftwareFoundation/openvdb ${{ github.sha }}

          Signed-off-by: ${{ github.actor }} <${{ github.actor }}@users.noreply.github.com>"

  #############################################################################
  ################################ Coverage ###################################
  #############################################################################

  linux-coverage:
    if: |
      github.repository_owner == 'AcademySoftwareFoundation' &&
      github.event_name == 'workflow_dispatch' &&
      github.event.inputs.deploy == 'coverage'
    runs-on: ubuntu-latest
    container:
      image: aswf/ci-openvdb:2025-clang19.1
    env:
      CXX: g++
    steps:
    - uses: actions/checkout@v3
    - name: install_gcovr
      run: pip install gcovr
    - name: build
      run: >
        ./ci/build.sh -v
        --build-type=coverage
        --components="core,axcore,test,axtest"
        --cargs=\"-DOPENVDB_CORE_STATIC=OFF -DOPENVDB_AX_STATIC=OFF\"
    - name: test_and_gcov
      run: |
        cd build
        ctest -V
        make gcov_html
        cd -
    - name: zip_large_html
      # The index.function list is > 100mb. Just zip it and provide it as a
      # download (could instead use LFS to host but not really worth it).
      run: |
        cd build/gcov_html
        tar -czvf index.functions.html.tar.gz index.functions.html
        sed -i -e 's/index.functions.html/index.functions.html.tar.gz/g' index.html
        sed -i -e 's/List of functions/Download function index/g' index.html
        rm index.functions.html
        cd -
    - name: pre_deploy
      # Overwrite global SSH configuration
      #  https://github.com/peaceiris/actions-gh-pages/issues/719
      #  https://linuxhint.com/ssh-stricthostkeychecking/
      run: >
        echo "Host *
          StrictHostKeyChecking no
          UserKnownHostsFile=/dev/null
        " > /etc/ssh/ssh_config
    - name: deploy
      uses: peaceiris/actions-gh-pages@v3
      with:
        deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
        publish_dir: ./build/gcov_html
        destination_dir: documentation/code_coverage
        external_repository: AcademySoftwareFoundation/openvdb-website
        publish_branch: master
        full_commit_message: "Automatic code coverage update
          - Deployed from: AcademySoftwareFoundation/openvdb ${{ github.sha }}

          Signed-off-by: ${{ github.actor }} <${{ github.actor }}@users.noreply.github.com>"