Set up workflow to build just the documentation.

.github/workflows/android.yml

@@ -19,7 +19,23 @@ on:
       - 'v[0-9]+.[0-9]+.[0-9]+-*'
     paths-ignore:
       - .appveyor.yml
+      - .github/workflows/check-mkvk.yml
+      - .github/workflows/docs.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
+      - install-gitconfig*
+      - vcpkg.json
+      - vcpkg-configuration.json
 
   # Allow manual trigger
   workflow_dispatch:

.github/workflows/check-mkvk.yml

@@ -19,7 +19,22 @@ on:
       - 'v[0-9]+.[0-9]+.[0-9]+-*'
     paths-ignore:
       - .appveyor.yml
+      - .github/workflows/docs.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
+      - install-gitconfig*
+      - vcpkg.json
+      - vcpkg-configuration.json
 
   # Allow manual trigger
   workflow_dispatch:

.github/workflows/docs.yml

@@ -3,6 +3,19 @@
 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,
@@ -33,7 +46,6 @@ on:
       - LICENSES
       - RELEASE_NOTES.md
       - REUSE.toml
-      - install-gitconfig*
       - vcpkg.json
       - vcpkg-configuration.json
 
@@ -45,7 +57,8 @@ jobs:
     name: Build KTX-Software reference pages and documentation
     strategy:
       matrix:
-        os: [ macos-latest,  ubuntu-latest, windows-latest ]
+        #os: [ macos-latest,  ubuntu-latest, windows-latest ]
+        os: [ ubuntu-latest ]
 
     runs-on: ${{ matrix.os }}
 
@@ -60,51 +73,25 @@ jobs:
         # included (used for version creation)
         fetch-depth: 0
 
-    - name: Install Doxygen and Graphviz on macOS
-      if: matrix.os == 'macos-latest'
-      run: brew install --formula doxygen && brew install --formula graphviz && echo "Doxygen version $(doxygen --version)"
+    - name: Set up Python 3.11
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11.4'
 
-    - name: Install Doxygen and Graphviz on Ubuntu
-      if: matrix.os == 'ubuntu-latest'
-      run: sudo apt-get install -y doxygen graphviz && echo "Doxygen version $(doxygen --version)"
-
-    - name: Install Doxygen and Graphviz on Windows
-      if: matrix.os == 'windows-latest'
-      #run: choco install doxygen.install
-      #run: choco install graphviz
-      # Note these suffer frequent failures due to Chocolatey attempts
-      # to blackmail you into purchasing a license. Hence we retry a
-      # few times. If this still fails, re-run the build.
-      run: |
-        function Install-WithChoco {
-            param ( $Package )
-            $retryCount = 4
-            $success = $false
-            for ($i = 1; $i -le $retryCount; $i++) {
-                Write-Host "Attempt no $i for $Package"
-                # Without | Out-Host the choco output becomes output of this
-                # function because it is called from within `if`.
-                choco install $Package --no-progress --yes | Out-Host
-                if ($LASTEXITCODE -eq 0) {
-                    $success = $true
-                    Write-Host "$Package installation successful."
-                    break
-                } else {
-                    Write-Host "$Package installation failed. Retrying..."
-                    Start-Sleep -Seconds (2*$i)
-                }
-            }
-            if (-not $success) {
-                Write-Host "$Package installation failed after $retryCount attempts."
-            }
-            return $success
-        }
-        if (-not ((Install-WithChoco doxygen.install) -and (Install-WithChoco graphviz))) {
-            exit 1
-        }
-        Import-Module "$env:ChocolateyInstall/helpers/chocolateyInstaller.psm1"
-        refreshenv
-        echo "Doxygen version $(doxygen --version)"
+    # 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'
@@ -115,38 +102,49 @@ jobs:
       run: ./install-gitconfig.ps1 && scripts/smudge_date.ps1
 
     - name: Build docs
-      run: | 
-        cmake -B ${{ env.BUILD_DIR }} -D KTX_FEATURE_DOC=ON -D KTX_FEATURE_TESTS=OFF -D KTX_FEATURE_TOOLS=OFF
+      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: Patch .nojekyll
+      # Some files in the pyktx docs have an _ prefix so Jekyll will
+      # not copy them from the gh-pages branch to the website. This
+      # file says no Jekyll files here. Treat all as ordinary files.
+#      if: matrix.os == 'ubuntu-latest'
+#      run: touch ${{ env.BUILD_DIR }}/docs/html/.nojekyll
+
     - 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`.
+  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'
-#
-#    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
+    # 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

.github/workflows/mingw.yml

@@ -19,8 +19,23 @@ on:
       - 'v[0-9]+.[0-9]+.[0-9]+-*'
     paths-ignore:
       - .appveyor.yml
+      - .github/workflows/android.yml
+      - .github/workflows/check-mkvk.yml
+      - .github/workflows/docs.yml
+      - .github/workflows/formatting.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
+      - install-gitconfig*
+      - vcpkg.json
+      - vcpkg-configuration.json
   # Allow manual trigger
   workflow_dispatch:
 

.github/workflows/windows.yml

@@ -19,7 +19,20 @@ on:
       - 'v[0-9]+.[0-9]+.[0-9]+-*'
     paths-ignore:
       - .appveyor.yml
+      - .github/workflows/android.yml
+      - .github/workflows/check-mkvk.yml
+      - .github/workflows/docs.yml
+      - .github/workflows/mingw.yml
+      - .github/workflows/publish-pyktx.yml
       - .travis.yml
+      - README.md
+      - CODE_OF_CONDUCT.md
+      - CONTRIBUTING.md
+      - LICENSE.md
+      - LICENSES
+      - REUSE.toml
+      - vcpkg.json
+      - vcpkg-configuration.json
 
   # Allow manual trigger
   workflow_dispatch:
@@ -62,7 +75,7 @@ jobs:
             arch: x64
             options: {
               config: 'Debug,Release',
-              doc: ON, jni: ON, loadtests: OpenGL+Vulkan, py: ON, tests: ON, tools: ON, tools_cts: ON,
+              doc: OFF, jni: ON, loadtests: OpenGL+Vulkan, py: ON, tests: ON, tools: ON, tools_cts: ON,
               package: NO,
               sse: ON, opencl: OFF
             }
@@ -159,41 +172,12 @@ jobs:
       if: github.ref_type == 'tag' && matrix.check_mkvk != 'ONLY'
       run: git fetch -f origin ${{ github.ref }}:${{ github.ref }}
 
-    # Need doxygen and graphviz if docs are supposed to be built.
-    # Note these suffer frequent failures due to Chocolatey attempts
-    # to blackmail you into purchasing a license. Hence we retry a
-    # few times. If this still fails, re-run the build.
-    - name: Install Doxygen and Graphviz
-      if: matrix.options.doc == 'ON'
-      #run: choco install doxygen.install
-      #run: choco install graphviz
-      run: |
-        function Install-WithChoco {
-            param ( $Package )
-            $retryCount = 4
-            $success = $false
-            for ($i = 1; $i -le $retryCount; $i++) {
-                Write-Host "Attempt no $i for $Package"
-                # Without | Out-Host the choco output becomes output of this
-                # function because it is called from within `if`.
-                choco install $Package --no-progress --yes | Out-Host
-                if ($LASTEXITCODE -eq 0) {
-                    $success = $true
-                    Write-Host "$Package installation successful."
-                    break
-                } else {
-                    Write-Host "$Package installation failed. Retrying..."
-                    Start-Sleep -Seconds (2*$i)
-                }
-            }
-            if (-not $success) {
-                Write-Host "$Package installation failed after $retryCount attempts."
-            }
-            return $success
-        }
-        if (-not ((Install-WithChoco doxygen.install) -and (Install-WithChoco graphviz))) {
-            exit 1
-        }
+    - name: Install Doxygen
+      uses: ssciwr/doxygen-install@v1
+
+    - name: Install Graphviz
+      uses: ts-graphviz/setup-graphviz@v2
+
     - name: Install AzureSignTool
       if: matrix.check_mkvk != 'ONLY'
       id: install-ast

.travis.yml

@@ -53,7 +53,7 @@ env:
     # runs on x86_64)
     - CONFIGURATION=Debug,Release PLATFORM=macOS ARCHS=x86_64
       FEATURE_DOC=ON FEATURE_JNI=ON FEATURE_PY=ON FEATURE_LOADTESTS=OpenGL+Vulkan FEATURE_TOOLS=ON
-      FEATURE_TOOLS_CTS=ON SUPPORT_SSE=ON SUPPORT_OPENCL=OFF DEPLOY_DOCS=YES PACKAGE=YES
+      FEATURE_TOOLS_CTS=ON SUPPORT_SSE=ON SUPPORT_OPENCL=OFF DEPLOY_DOCS=NO PACKAGE=YES
     - CONFIGURATION=Release PLATFORM=macOS ARCHS=arm64
       FEATURE_DOC=ON FEATURE_JNI=ON FEATURE_PY=OFF FEATURE_LOADTESTS=OpenGL+Vulkan FEATURE_TESTS=OFF
       FEATURE_TOOLS=ON FEATURE_TOOLS_CTS=OFF SUPPORT_SSE=ON SUPPORT_OPENCL=OFF PACKAGE=YES

cmake/docs.cmake

@@ -210,7 +210,7 @@ function( CreateDocPyktxWrappers )
         COMMAND
             ${CMAKE_COMMAND} -E copy_directory ${KTX_BUILD_DIR}/interface/python_binding/docs/html/pyktx/html ${KTX_BUILD_DIR}/docs/html/pyktx
     )
-    add_dependencies( libktx.doc pyktx )
+    add_dependencies( libktx.doc pyktx.doc )
 endfunction()
 
 # ktxpkg.doc