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 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: Build C++
        working-directory: ./cpp
        run: make V=1 srcs

      - 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

      - name: Generate Documentation for Swift
        working-directory: ./swift
        run: |
          make V=1 srcs

          xcodebuild docbuild \
            -project ice.xcodeproj \
            -scheme 'Ice macOS' \
            -derivedDataPath /tmp/docbuild \
            -destination 'generic/platform=macOS'

          mkdir docs

          $(xcrun --find docc) process-archive \
            transform-for-static-hosting /tmp/docbuild/Build/Products/Debug/Ice.doccarchive \
            --hosting-base-path /api/ice/main/swift/ice \
            --output-path docs/ice;

          $(xcrun --find docc) process-archive \
            transform-for-static-hosting /tmp/docbuild/Build/Products/Debug/Glacier2.doccarchive \
            --hosting-base-path /api/ice/main/swift/glacier2 \
            --output-path docs/glacier2;

          $(xcrun --find docc) process-archive \
            transform-for-static-hosting /tmp/docbuild/Build/Products/Debug/IceGrid.doccarchive \
            --hosting-base-path /api/ice/main/swift/icegrid \
            --output-path docs/icegrid;

          $(xcrun --find docc) process-archive \
            transform-for-static-hosting /tmp/docbuild/Build/Products/Debug/IceStorm.doccarchive \
            --hosting-base-path /api/ice/main/swift/icestorm \
            --output-path docs/icestorm;

      # 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

          aws s3 sync ./swift/docs/ice s3://${AWS_S3_DOC_BUCKET}/api/ice/main/swift/ice --delete
          aws s3 sync ./swift/docs/glacier2 s3://${AWS_S3_DOC_BUCKET}/api/ice/main/swift/glacier2 --delete
          aws s3 sync ./swift/docs/icegrid s3://${AWS_S3_DOC_BUCKET}/api/ice/main/swift/icegrid --delete
          aws s3 sync ./swift/docs/icestorm s3://${AWS_S3_DOC_BUCKET}/api/ice/main/swift/icestorm  --delete

        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'