docs.yml

# Copyright Contributors to the OpenImageIO project.
# SPDX-License-Identifier: Apache-2.0
# https://github.com/AcademySoftwareFoundation/OpenImageIO

name: docs

on:
  push:
    # Skip jobs when only cpp files are changed. The materials for
    # docs are all in md, rst, and .h files.
    paths-ignore:
      - '**/ci.yml'
      - '**/analysis.yml'
      - '**.properties'
      - 'src/**.cpp'
      - '**.cmake'
      - '**/run.py'
  pull_request:
    paths-ignore:
      - '**/ci.yml'
      - '**/analysis.yml'
      - '**.properties'
      - 'src/**.cpp'
      - '**.cmake'
      - '**/run.py'
  schedule:
    # Full nightly build
    - cron: "0 8 * * *"
      if: github.repository == 'AcademySoftwareFoundation/OpenImageIO'
  workflow_dispatch:
    # This allows manual triggering of the workflow from the web

permissions: read-all


jobs:

  aswf:
    name: "Docs / VFX${{matrix.vfxyear}} ${{matrix.desc}}"
    strategy:
      fail-fast: false
      matrix:
        include:
          - desc: docs
            nametag: docslinux
            runner: ubuntu-latest
            container: aswftesting/ci-openexr:2024
            vfxyear: 2024
            cxx_std: 17
            python_ver: "3.11"
            build_docs: 1
            skip_build: 1
            skip_tests: 1
            setenvs: export EXTRA_DEP_PACKAGES="doxygen sphinx-doc"
                            PIP_INSTALLS="sphinx breathe sphinx-tabs furo"

    runs-on: ${{ matrix.runner }}
    container:
      image: ${{ matrix.container }}
    env:
      CXX: ${{matrix.cxx_compiler}}
      CC: ${{matrix.cc_compiler}}
      CMAKE_CXX_STANDARD: ${{matrix.cxx_std}}
      USE_SIMD: ${{matrix.simd}}
      FMT_VERSION: ${{matrix.fmt_ver}}
      OPENCOLORIO_VERSION: ${{matrix.opencolorio_ver}}
      OPENEXR_VERSION: ${{matrix.openexr_ver}}
      PYBIND11_VERSION: ${{matrix.pybind11_ver}}
      PYTHON_VERSION: ${{matrix.python_ver}}
      ABI_CHECK: ${{matrix.abi_check}}
      ACTIONS_RUNNER_FORCE_ACTIONS_NODE_VERSION: node16
      ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION: true
    steps:
      # We would like to use harden-runner, but it flags too many false
      # positives, every time we download a dependency. We should use it only
      # on CI runs where we are producing artifacts that users might rely on.
      # - name: Harden Runner
      #   uses: step-security/harden-runner@248ae51c2e8cc9622ecf50685c8bf7150c6e8813 # v1.4.3
      #   with:
      #     egress-policy: audit # TODO: change to 'egress-policy: block' after couple of runs
      - uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744 # v3.6.0
        # Note: can't upgrade to actions/checkout 4.0 because it needs newer
        # glibc than these containers have.
      - name: Prepare ccache timestamp
        id: ccache_cache_keys
        run: echo "date=`date -u +'%Y-%m-%dT%H:%M:%SZ'`" >> $GITHUB_OUTPUT
      - name: ccache
        id: ccache
        uses: actions/cache@e12d46a63a90f2fae62d114769bbf2a179198b5c # v3.3.3
        # Note: can't upgrade to actions/cache 4.0 because it needs newer
        # glibc than these containers have.
        with:
          path: /tmp/ccache
          key: ${{github.job}}-${{matrix.nametag}}-${{steps.ccache_cache_keys.outputs.date}}
          restore-keys: ${{github.job}}-
      - name: Build setup
        run: |
            ${{matrix.setenvs}}
            src/build-scripts/ci-startup.bash
      - name: Dependencies
        run: |
            ${{matrix.depcmds}}
            src/build-scripts/gh-installdeps.bash
      - name: Build
        if: matrix.skip_build != '1'
        run: src/build-scripts/ci-build.bash
      - name: Testsuite
        if: matrix.skip_tests != '1'
        run: src/build-scripts/ci-test.bash
      - name: Check out ABI standard
        if: matrix.abi_check != ''
        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
        with:
          ref: ${{matrix.abi_check}}
          path: abi_standard
      - name: Build ABI standard
        if: matrix.abi_check != ''
        run: |
            mkdir -p abi_standard/build
            pushd abi_standard
            src/build-scripts/ci-build.bash
            popd
      - name: Check ABI
        if: matrix.abi_check != ''
        run: |
            src/build-scripts/ci-abicheck.bash ./build abi_standard/build libOpenImageIO libOpenImageIO_Util
      - name: Build Docs
        if: matrix.build_docs == '1'
        run: |
            cd src/doc
            time make doxygen
            time make sphinx
      - uses: actions/upload-artifact@a8a3f3ad30e3422c9c7b888a15615d19a852ae32 # v3.1.3
        # Note: versions of upload-artifact >= 4.0 can't run on the ASWF
        # containers because they need a newer glibc than they have.
        if: ${{ failure() || matrix.build_docs == '1'}}
        with:
          name: oiio-${{github.job}}-${{matrix.nametag}}
          path: |
            build/cmake-save
            build/compat_reports
            build/sphinx
            build/testsuite/*/*.*
            !build/testsuite/oiio-images
            !build/testsuite/openexr-images
            !build/testsuite/fits-images
            !build/testsuite/j2kp4files_v1_5