docs.yml

name: Generate documentation

on:
  workflow_dispatch:
  push:
    branches: ["main"]
  pull_request:
    # The branches below must be a subset of the branches above
    branches: ["main"]

jobs:
  ci:
    name: Build Doxygen documentation

    runs-on: macos-14
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Dependencies
        uses: ./.github/actions/setup-dependencies
        with:
          use_ccache: false

      - name: Install awscli
        run: brew install awscli || true

      - name: Install doxygen and graphviz (a dependency of Doxygen for generating diagrams)
        run: brew install doxygen graphviz || true

      - name: Generate Doxygen Documentation for Slice
        working-directory: ./doxygen
        run: doxygen

      - name: Generate Doxygen Documentation for C++
        working-directory: ./cpp
        run: |
          make generate-srcs
          cd doxygen
          doxygen

      # This will perform a full sync of the documentation to S3 every time the workflow is run since
      # the timestamps will always be different. Using --size-only is not sufficient since the
      # documentation may be updated without changing the size of the files. S3 does not offer a hash based sync.
      #
      # Additionally, we do not cache the doxygen output since it does not remove files old files.
      - name: Sync Documentation to S3
        run: |
          aws s3 sync ./doxygen/slice s3://${AWS_S3_DOC_BUCKET}/api/ice/main/slice --delete
          aws s3 cp ./doxygen/slice.tag s3://${AWS_S3_DOC_BUCKET}/api/ice/main/slice.tag

          aws s3 sync ./cpp/doxygen/cpp s3://${AWS_S3_DOC_BUCKET}/api/ice/main/cpp --delete
          aws s3 cp ./cpp/doxygen/icecpp.tag s3://${AWS_S3_DOC_BUCKET}/api/ice/main/icecpp.tag
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          AWS_S3_DOC_BUCKET: ${{ secrets.AWS_S3_DOC_BUCKET }}
          AWS_DEFAULT_REGION: us-east-1
        if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'