From 3d84b3cfa7055e690123707b1138ffa5ce9f9896 Mon Sep 17 00:00:00 2001 From: Joe George Date: Fri, 24 Jan 2025 16:49:41 -0500 Subject: [PATCH] Merge doc workflow into CI workflow (#3417) --- .github/actions/documentation/action.yml | 105 ++++++++++++++++++++ .github/workflows/ci.yml | 8 ++ .github/workflows/docs.yml | 116 ----------------------- 3 files changed, 113 insertions(+), 116 deletions(-) create mode 100644 .github/actions/documentation/action.yml delete mode 100644 .github/workflows/docs.yml diff --git a/.github/actions/documentation/action.yml b/.github/actions/documentation/action.yml new file mode 100644 index 00000000000..4ed6fb9240b --- /dev/null +++ b/.github/actions/documentation/action.yml @@ -0,0 +1,105 @@ +name: API Reference +description: Generate API reference documentation for Ice +inputs: + aws-access-key-id: + description: "AWS access key ID" + required: true + aws-secret-access-key: + description: "AWS secret access key" + required: true + aws-s3-code-bucket: + description: "AWS S3 bucket for storing the API reference" + required: true + +runs: + using: "composite" + steps: + # 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 + shell: bash + + - name: Install docfx for C# API reference + run: dotnet tool install -g docfx + shell: bash + + - name: Generate Doxygen API reference for Slice + working-directory: ./doxygen + run: doxygen + shell: bash + + - name: Generate Doxygen API reference for C++ + working-directory: ./cpp/doxygen + run: doxygen + shell: bash + + - name: Generate TypeDoc API reference for JavaScript + working-directory: ./js + run: make doc + shell: bash + + - name: Generate docfx API reference for C# + working-directory: ./csharp/docfx + run: | + docfx metadata --property Configuration=Release + docfx build + shell: bash + + - name: Generate Python API reference + working-directory: ./python/docs + run: | + pip install -r requirements.txt + make html + shell: bash + + - 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 /ice/main/api/swift/$target + done + shell: bash + + - name: Generate API reference for Java + working-directory: ./java + run: | + make -C ../cpp slice2java + ./gradlew :alljavadoc + shell: bash + + # 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_CODE_BUCKET}/ice/main/api/slice --delete + aws s3 cp ./doxygen/slice.tag s3://${AWS_S3_CODE_BUCKET}/ice/main/api/slice.tag + + aws s3 sync ./cpp/doxygen/cpp s3://${AWS_S3_CODE_BUCKET}/ice/main/api/cpp --delete + aws s3 cp ./cpp/doxygen/icecpp.tag s3://${AWS_S3_CODE_BUCKET}/ice/main/api/icecpp.tag + + aws s3 sync ./csharp/docfx/_site s3://${AWS_S3_CODE_BUCKET}/ice/main/api/csharp --delete + + aws s3 sync ./js/docs s3://${AWS_S3_CODE_BUCKET}/ice/main/api/js --delete + + aws s3 sync ./python/docs/_build/html s3://${AWS_S3_CODE_BUCKET}/ice/main/api/python --delete + + for target in Ice Glacier2 IceGrid IceStorm; do + aws s3 sync ./swift/docs/$target s3://${AWS_S3_CODE_BUCKET}/ice/main/api/swift/$target --delete + done + + aws s3 sync ./java/build/docs/javadoc s3://${AWS_S3_CODE_BUCKET}/ice/main/api/java --delete + + env: + AWS_ACCESS_KEY_ID: ${{ inputs.aws-access-key-id }} + AWS_SECRET_ACCESS_KEY: ${{ inputs.aws-secret-access-key }} + AWS_S3_CODE_BUCKET: ${{ inputs.aws-s3-code-bucket }} + AWS_DEFAULT_REGION: us-east-1 + shell: bash + if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request' diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 74cfc9025f4..74c3112d4e7 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -141,6 +141,14 @@ jobs: flags: ${{ matrix.cross_test_flags }} if: matrix.cross_test_flags != '' + - name: Generate API Reference + uses: ./.github/actions/documentation + with: + aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }} + aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }} + aws-s3-code-bucket: ${{ secrets.AWS_S3_CODE_BUCKET }} + if: matrix.config == 'release' && runner.os == 'macOS' + - name: Upload test logs uses: actions/upload-artifact@v4 with: diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml deleted file mode 100644 index 6e8f0218372..00000000000 --- a/.github/workflows/docs.yml +++ /dev/null @@ -1,116 +0,0 @@ -name: Documentation - -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 /ice/main/api/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_CODE_BUCKET}/ice/main/api/slice --delete - aws s3 cp ./doxygen/slice.tag s3://${AWS_S3_CODE_BUCKET}/ice/main/api/slice.tag - - aws s3 sync ./cpp/doxygen/cpp s3://${AWS_S3_CODE_BUCKET}/ice/main/api/cpp --delete - aws s3 cp ./cpp/doxygen/icecpp.tag s3://${AWS_S3_CODE_BUCKET}/ice/main/api/icecpp.tag - - aws s3 sync ./csharp/docfx/_site s3://${AWS_S3_CODE_BUCKET}/ice/main/api/csharp --delete - - aws s3 sync ./js/docs s3://${AWS_S3_CODE_BUCKET}/ice/main/api/js --delete - - aws s3 sync ./python/docs/_build/html s3://${AWS_S3_CODE_BUCKET}/ice/main/api/python --delete - - for target in Ice Glacier2 IceGrid IceStorm; do - aws s3 sync ./swift/docs/$target s3://${AWS_S3_CODE_BUCKET}/ice/main/api/swift/$target --delete - done - - aws s3 sync ./java/build/docs/javadoc s3://${AWS_S3_CODE_BUCKET}/ice/main/api/java --delete - - env: - AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} - AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }} - AWS_S3_CODE_BUCKET: ${{ secrets.AWS_S3_CODE_BUCKET }} - AWS_DEFAULT_REGION: us-east-1 - if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'