Add files using upload-large-folder tool

a95d691 verified 12 days ago

5 kB

# 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-mkvk.yml
      - .github/workflows/formatting.yml
      - .github/workflows/mingw.yml
      - .github/workflows/publish-pyktx.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

	# 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-mkvk.yml
	- .github/workflows/formatting.yml
	- .github/workflows/mingw.yml
	- .github/workflows/publish-pyktx.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