Build and publish template documentation #32
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: verify_template_docs | |
| run-name: Build and publish template documentation | |
| on: | |
| workflow_dispatch: | |
| inputs: | |
| deploy_pages: | |
| description: "Deploy to GitHub Pages after building docs" | |
| required: true | |
| default: false | |
| type: boolean | |
| push: | |
| branches: | |
| - "master" | |
| - "main" | |
| - "develop" | |
| paths: | |
| - README.md | |
| - src/** | |
| - doc/** | |
| - cmake/** | |
| - CMakeLists.txt | |
| - CMakePresets.json | |
| - .github/workflows/docs_pages.yml | |
| - .github/workflows/docs_pages.yml.tpl | |
| - tests/template_test/testWorkflowTemplates.py | |
| pull_request: | |
| branches: | |
| - "master" | |
| - "main" | |
| - "develop" | |
| - "dev*" | |
| paths: | |
| - README.md | |
| - src/** | |
| - doc/** | |
| - cmake/** | |
| - CMakeLists.txt | |
| - CMakePresets.json | |
| - .github/workflows/docs_pages.yml | |
| - .github/workflows/docs_pages.yml.tpl | |
| - tests/template_test/testWorkflowTemplates.py | |
| permissions: | |
| contents: read | |
| concurrency: | |
| group: pages-${{ github.ref }} | |
| cancel-in-progress: true | |
| jobs: | |
| build-docs: | |
| runs-on: ubuntu-latest | |
| env: | |
| BUILD_DIR: build_docs | |
| steps: | |
| - name: Checkout repository | |
| uses: actions/checkout@v6 | |
| with: | |
| fetch-depth: 0 | |
| - name: Install documentation dependencies | |
| run: | | |
| sudo apt update | |
| sudo apt install -y cmake ninja-build g++ doxygen graphviz libeigen3-dev python3-pytest python3-yaml | |
| - name: Run template workflow contracts | |
| id: workflow_contracts | |
| run: python3 -m pytest -q tests/template_test/testWorkflowTemplates.py | |
| - name: Configure documentation build | |
| run: | | |
| cmake -S . -B "${BUILD_DIR}" -GNinja \ | |
| -DCMAKE_BUILD_TYPE=RelWithDebInfo \ | |
| -DENABLE_TESTS=OFF \ | |
| -DENABLE_CUDA=OFF \ | |
| -DENABLE_OPTIX=OFF \ | |
| -DENABLE_OPENGL=OFF \ | |
| -DBUILD_DOC_HTML=ON \ | |
| -DBUILD_DOC_XML=ON \ | |
| -DBUILD_DOC_LATEX=OFF \ | |
| -DDOC_WARN_AS_ERROR=OFF \ | |
| -Dtemplate_project_BUILD_PROGRAMS=OFF \ | |
| -Dtemplate_project_BUILD_EXAMPLES=OFF | |
| - name: Build documentation | |
| run: cmake --build "${BUILD_DIR}" --target doc --parallel 2 | |
| - name: Verify generated site | |
| run: | | |
| test -f "${BUILD_DIR}/doc/html/index.html" | |
| test -d "${BUILD_DIR}/doc/xml" | |
| - name: Upload Pages artifact | |
| uses: actions/upload-pages-artifact@v5 | |
| with: | |
| path: ${{ env.BUILD_DIR }}/doc/html | |
| deploy: | |
| if: ${{ (github.event_name == 'push' && github.ref == format('refs/heads/{0}', github.event.repository.default_branch)) || (github.event_name == 'workflow_dispatch' && inputs.deploy_pages) }} | |
| needs: build-docs | |
| runs-on: ubuntu-latest | |
| permissions: | |
| pages: write | |
| id-token: write | |
| environment: | |
| name: github-pages | |
| url: ${{ steps.deployment.outputs.page_url }} | |
| steps: | |
| - name: Configure Pages | |
| uses: actions/configure-pages@v6 | |
| - name: Deploy to GitHub Pages | |
| id: deployment | |
| uses: actions/deploy-pages@v5 | |
| - name: Verify published Pages output | |
| run: | | |
| curl --fail --location --retry 5 --retry-delay 5 \ | |
| "${{ steps.deployment.outputs.page_url }}" \ | |
| --output /tmp/docs-pages-index.html | |
| grep -F "Template usage" /tmp/docs-pages-index.html | |
| grep -F "Documentation workflow" /tmp/docs-pages-index.html | |
| grep -F "Versioning" /tmp/docs-pages-index.html |