docs.yml

name: Generate API Reference

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

jobs:
  api-reference:
    runs-on: macos-15
    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

      # Use --formula to silence homebrew warning when installing doxygen from a formula.
      - name: Install doxygen and graphviz (a dependency of Doxygen for generating diagrams)
        run: |
          brew install graphviz || true
          brew install doxygen --formula || true

      - name: Install docfx for C# API reference
        run: dotnet tool install -g docfx

      - name: Build C++
        working-directory: ./cpp
        run: make V=1 srcs

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

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

      - name: Generate TypeDoc API reference for JavaScript
        working-directory: ./js
        run: |
          make doc

      - name: Generate docfx API reference for C#
        working-directory: ./csharp/docfx
        run: |
          make -C ../../cpp slice2cs
          make -C ../
          docfx metadata --property Configuration=Release
          docfx build

      - name: Generate Python API reference
        working-directory: ./python/docs
        run: |
          make -C ../../cpp slice2py Ice IceDiscovery IceLocatorDiscovery
          make -C ../
          pip install -r requirements.txt
          make html

      - name: Generate API reference for Swift
        run: |
          mkdir ./swift/docs

          for target in Ice Glacier2 IceGrid IceStorm; do
            swift package --allow-writing-to-directory ./swift/docs generate-documentation --output-path ./swift/docs/$target \
              --target $target --transform-for-static-hosting --hosting-base-path  /api/ice/main/swift/$target
          done

      - name: Generate API reference for Java
        working-directory: ./java
        run: |
          make -C ../cpp slice2java
          ./gradlew :alljavadoc

      # 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 ./csharp/docfx/_site s3://${AWS_S3_DOC_BUCKET}/api/ice/main/csharp --delete

          aws s3 sync ./js/docs s3://${AWS_S3_DOC_BUCKET}/api/ice/main/js --delete

          aws s3 sync ./python/docs/_build/html s3://${AWS_S3_DOC_BUCKET}/api/ice/main/python --delete

          for target in Ice Glacier2 IceGrid IceStorm; do
            aws s3 sync ./swift/docs/$target s3://${AWS_S3_DOC_BUCKET}/api/ice/main/swift/$target --delete
          done

          aws s3 sync ./java/build/docs/javadoc s3://${AWS_S3_DOC_BUCKET}/api/ice/main/java --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'