docs.yml

# Copyright 2025 The Khronos Group Inc.
# SPDX-License-Identifier: Apache-2.0
name: Build and Deploy Reference Pages and Other Documentation

# Ensure documentation builds on all platforms. Deploy from the Ubuntu build.
#
#   The plan is for this to be used to build the docs on all platforms for
# PRs and pushes to main and remove those builds from the platform software
# builds. On release tags though the platform software builsd will have to
# build the documentation so it can be included in the release package.
#   Due to a tight deadline for 4.4 there is no time to modify the platform
# software builds to build docs only on release tags so they continue to
# build for PRs and pushes to main. Therefore all but the Ubuntu build have
# been disabled here for now.
#   The ubuntu build is used to deploy the docs to GitHub Pages on a release
# build. The plan, once the destination is set up, is to use this workflow
# to deploy the docs for a release to a location on khronos.org and docs
# for any pushes to main to GitHub Pages.

on:
  # Trigger the workflow on a pull request,
  pull_request:

  push:
    # And on pushes to main, which will occur when a PR is merged.
    branches:
      - main
    # Also trigger on push of release tags to any branch. Useful
    # for testing release builds before merging to main.
    tags:
      - 'v[0-9]+.[0-9]+.[0-9]+'
      - 'v[0-9]+.[0-9]+.[0-9]+-*'
    paths-ignore:
      - .appveyor.yml
      - .github/workflows/android.yml
      - .github/workflows/check-libktx-only.yml
      - .github/workflows/check-mkvk.yml
      - .github/workflows/check-reuse.yml
      - .github/workflows/formatting.yml
      - .github/workflows/linux.yml
      - .github/workflows/macos.yml
      - .github/workflows/mingw.yml
      - .github/workflows/publish-pyktx.yml
      - .github/workflows/manual.yml
      - .github/workflows/web.yml
      - .github/workflows/windows.yml
      - .travis.yml
      - README.md
      - CODE_OF_CONDUCT.md
      - CONTRIBUTING.md
      - LICENSE.md
      - LICENSES
      - RELEASE_NOTES.md
      - REUSE.toml
      - vcpkg.json
      - vcpkg-configuration.json

  # Allow manual trigger
  workflow_dispatch:

env:
 GIT_LFS_SKIP_SMUDGE: 1

jobs:
  build-docs:
    name: Build KTX-Software reference pages and documentation
    strategy:
      matrix:
        #os: [ macos-latest,  ubuntu-latest, windows-latest ]
        os: [ ubuntu-latest ]

    runs-on: ${{ matrix.os }}

    env:
      BUILD_DIR: build

    steps:
    - uses: actions/checkout@v4
      with:
        # Fetch all history to make sure tags are
        # included (used for version creation)
        fetch-depth: 0

    - name: Force fetch provoking tag's annotation.
      # Work around https://github.com/actions/checkout/issues/290.
      if: github.ref_type == 'tag'
      run: git fetch -f origin ${{ github.ref }}:${{ github.ref }}

    - name: Set up Python 3.11
      uses: actions/setup-python@v5
      with:
        python-version: '3.11.4'

    # virtualenv is no longer included as of 20240929.1 runner so
    # install it ourselves. See
    # https://github.com/actions/runner-images/issues/10749.
    #
    # Note that it is the builds of sdist and wheel that require virtualenv
    # not the explicit dependencies of pyktx.
    - name: Install Python virtualenv
      run: pip install virtualenv

    - name: Install Doxygen
      uses: ssciwr/doxygen-install@v1

    - name: Install Graphviz
      uses: ts-graphviz/setup-graphviz@v2

    - name: Smudge dates (macOS and Ubuntu)
      if:  matrix.os == 'macos-latest' || matrix.os == 'ubuntu-latest'
      run: ./install-gitconfig.sh && scripts/smudge_date.sh

    - name: Smudge dates (Windows)
      if:  matrix.os == 'windows-latest'
      run: ./install-gitconfig.ps1 && scripts/smudge_date.ps1

    - name: Build docs
      run: |
        echo "Doxygen version: $(doxygen --version)"
        cmake -B ${{ env.BUILD_DIR }} -D KTX_FEATURE_DOC=ON -D KTX_FEATURE_PY=ON -D KTX_FEATURE_TESTS=OFF -D KTX_FEATURE_TOOLS=OFF
        cmake --build ${{ env.BUILD_DIR }} --target all.doc

    - name: Upload generated HTML documentation for GitHub Pages
      if: matrix.os == 'ubuntu-latest'
      id: deployment
      uses: actions/upload-pages-artifact@v3
      with:
        path: ${{ env.BUILD_DIR }}/docs/html

  deploy:
    name: Deploy to GitHub Pages
    # Add a dependency to the build job
    needs: build-docs
    # Only deploy when building `main`.
#    if: github.ref == 'refs/heads/main'
    # Only deploy when building for a release tag. Note that filtering in
    # on: means the only tags the workflow runs for are release tags.
    if: startsWith(github.ref, 'refs/tags')

    runs-on: ubuntu-latest

    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
    permissions:
      pages: write      # to deploy to Pages
      id-token: write   # to verify the deployment originates from an appropriate source

    # Deploy to the github-pages environment
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    # Specify deployment step
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4