documentation.yml

name: Documentation

on:
  push:
    branches: [ main ]
    tags: [ 'v*.*.*' ]
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-latest
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    env:
      upa_deploy: ${{ github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v') || '' }}
      upa_docs_repository: upa-url/docs
      # Used in Doxyfile: PROJECT_NUMBER = $(UPA_DOCS_VERSION)
      UPA_DOCS_VERSION: ${{ github.ref_name }}
    steps:
      - uses: actions/checkout@v4

      # Check C++ examples in documentation
      - name: Extract and try to build C++ examples from docs
        run: |
          tools/extract-cpp.py examples/extracted-cpp README.md
          cmake -S . -B build -DCMAKE_CXX_COMPILER=g++ -DCMAKE_CXX_STANDARD=20 -DUPA_BUILD_TESTS=OFF -DUPA_BUILD_EXTRACTED=ON
          cmake --build build

      # Install and run doxygen
      - name: Download theme
        run: doc/download-theme.sh
      - uses: ssciwr/doxygen-install@v1
        with:
          version: "1.11.0"
      - name: Run doxygen
        run: /usr/local/bin/doxygen

      # Deploy docs
      - name: Is there a gh-pages branch?
        if: env.upa_deploy
        run: echo "upa_checkout=$(git ls-remote --heads https://github.com/$upa_docs_repository.git refs/heads/gh-pages)" >> "$GITHUB_ENV"

      - name: Checkout ${{ env.upa_docs_repository }}
        uses: actions/checkout@v4
        if: env.upa_deploy && env.upa_checkout
        with:
          repository: ${{ env.upa_docs_repository }}
          ref: gh-pages
          path: build-docs

      - name: Update versions.txt
        if: env.upa_deploy
        run: |
          mkdir -p build-docs
          echo "upa_docs_dir=$(tools/update-docs-versions.py build-docs $GITHUB_REF)" >> "$GITHUB_ENV"

      - name: Prepare directory for publication
        if: env.upa_deploy && env.upa_docs_dir
        run: |
          sudo chown --recursive $USER doc/html
          rm -rf build-docs/.git
          rm -rf build-docs/common
          rm -rf build-docs/${{ env.upa_docs_dir }}
          cp -r doc/common build-docs/common
          mv doc/html build-docs/${{ env.upa_docs_dir }}
          cp doc/index.html build-docs

      - name: Deploy to ${{ env.upa_docs_repository }}
        uses: JamesIves/github-pages-deploy-action@v4
        if: env.upa_deploy && env.upa_docs_dir
        with:
          ssh-key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
          repository-name: ${{ env.upa_docs_repository }}
          folder: build-docs