From 21b92d0c2cfe854bd626d71faf5cbaf17cace309 Mon Sep 17 00:00:00 2001 From: Alexander Lanin Date: Tue, 17 Dec 2024 00:39:06 +0100 Subject: [PATCH] docs: preview in PRs --- .../actions/deploy-versioned-pages/action.yml | 79 +++++++++++++++++++ .github/workflows/docs-cleanup.yml | 50 ++++++++++++ .github/workflows/docs.yml | 54 +++++++------ 3 files changed, 159 insertions(+), 24 deletions(-) create mode 100644 .github/actions/deploy-versioned-pages/action.yml create mode 100644 .github/workflows/docs-cleanup.yml diff --git a/.github/actions/deploy-versioned-pages/action.yml b/.github/actions/deploy-versioned-pages/action.yml new file mode 100644 index 0000000..abc41d5 --- /dev/null +++ b/.github/actions/deploy-versioned-pages/action.yml @@ -0,0 +1,79 @@ +# ******************************************************************************* +# Copyright (c) 2024 Contributors to the Eclipse Foundation +# +# See the NOTICE file(s) distributed with this work for additional +# information regarding copyright ownership. +# +# This program and the accompanying materials are made available under the +# terms of the Apache License Version 2.0 which is available at +# https://www.apache.org/licenses/LICENSE-2.0 +# +# SPDX-License-Identifier: Apache-2.0 +# ******************************************************************************* + +name: Deploy Versioned Pages +description: Will push the documentation to the gh-pages branch, possibly with a versioned URL. When the PR is closed, the documentation will be deleted. +# Note: this has some shortcomings, like race conditions when multiple PRs are opened at the same time, +# problems with overwriting existing files, not deleting deleted files, etc. +# We'll address these when we transform this action into a truly reusable independent action. +# But for now, let's get it working! +inputs: + source_folder: + description: "Path to the html files to deploy in current working directory" + required: true + versions_file: + description: "Path to the versions file on gh-pages branch" + default: "versions" + create_comment: + description: "Create a comment on the PR with the URL to the documentation" # in case of PR + default: "true" +outputs: + target_folder: + description: "The target folder for the documentation" + value: ${{ steps.calc.outputs.target_folder }} +runs: + using: "composite" + steps: + - name: Determine target_folder + id: calc + shell: bash + run: | + if [[ ${{github.event_name}} == 'pull_request' ]]; then + echo "target_folder=pr-${{github.event.pull_request.number}}" >> $GITHUB_OUTPUT + elif [[ ${{github.ref_name}} != 'main' ]]; then + echo "target_folder=${{github.ref_name}}" >> $GITHUB_OUTPUT + else + echo "target_folder=/" >> $GITHUB_OUTPUT + fi + - name: Prepare + shell: bash + run: | + # Prepare the deploy folder + mkdir -p deploy_root/${{ steps.calc.outputs.target_folder }} + # Move the files to the deploy folder + mv ${{ inputs.source_folder }}/* deploy_root/${{ steps.calc.outputs.target_folder }} + # Ensure that the folder is not treated as a Jekyll site + touch deploy_root/.nojekyll + + # Add the target folder to the versions file + git fetch origin gh-pages --depth 1 + git checkout origin/gh-pages -- "${{ inputs.versions_file }}" + if ! grep -qx "${{ steps.calc.outputs.target_folder }}" "${{ inputs.versions_file }}"; then + echo "${{ steps.calc.outputs.target_folder }}" >> "${{ inputs.versions_file }}" + fi + mv "${{ inputs.versions_file }}" deploy_root/ + ls -al . + ls -al deploy_root + - name: Deploy 🚀 + uses: JamesIves/github-pages-deploy-action@v4 + with: + folder: deploy_root + clean: false + - name: Comment on PR with docs URL + if: ${{ github.event_name == 'pull_request' && inputs.create_comment == 'true' }} + uses: peter-evans/create-or-update-comment@v4 + with: + issue-number: ${{github.event.pull_request.number}} + body: | + The created documentation from the pull request is available at: [docu-html](https://eclipse-score.github.io/score/${{steps.calc.outputs.target_folder}}) + reactions: rocket diff --git a/.github/workflows/docs-cleanup.yml b/.github/workflows/docs-cleanup.yml new file mode 100644 index 0000000..32f59a1 --- /dev/null +++ b/.github/workflows/docs-cleanup.yml @@ -0,0 +1,50 @@ +# ******************************************************************************* +# Copyright (c) 2024 Contributors to the Eclipse Foundation +# +# See the NOTICE file(s) distributed with this work for additional +# information regarding copyright ownership. +# +# This program and the accompanying materials are made available under the +# terms of the Apache License Version 2.0 which is available at +# https://www.apache.org/licenses/LICENSE-2.0 +# +# SPDX-License-Identifier: Apache-2.0 +# ******************************************************************************* + +name: Cleanup Documentation +on: + pull_request: + types: [closed] + delete: +jobs: + docs-build-cleanup: + name: Remove build documentation + # Remove the corresponding documentation from the gh-pages branch, + # after a PR is closed or a branch is deleted. + runs-on: ubuntu-latest + concurrency: + group: gh-pages + cancel-in-progress: false + steps: + - uses: actions/checkout@v4 + with: + ref: gh-pages + - name: Remove version + run: | + if [[ ${{ github.event_name }} == "pull_request" ]]; then + VERSION="pr-${{ github.event.pull_request.number }}" + else + VERSION="${{ github.ref_name }}" + fi + + echo "VERSION=$VERSION" >> $GITHUB_ENV + + # Delete the folder and remove the version from the versions file + rm -rf "${VERSION}" + sed -i "/^$VERSION$/d" versions + - name: Push changes to gh-pages branch + uses: EndBug/add-and-commit@v9 + with: + message: "Cleanup ${{ env.VERSION }}" + add: . + new_branch: "gh-pages" diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 3c53757..e9e48ea 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -11,7 +11,7 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -name: Documentation build +name: Documentation on: pull_request: types: [opened, reopened, synchronize] @@ -22,6 +22,11 @@ on: types: [checks_requested] jobs: docs-build: + name: Build documentation + # Build the documentation and upload it as an artifact + + # TBD: maybe it's easier to separate `closed` into a separate workflow? + if: ${{ (github.event_name != 'pull_request' || github.event.action != 'closed') }} runs-on: ubuntu-latest permissions: pull-requests: write @@ -33,41 +38,42 @@ jobs: - name: Build documentation run: | bazel build //docs:github-pages && cp bazel-bin/docs/github-pages.tar . - - name: Upload artifact for deployment - if: github.event_name == 'push' && github.ref == 'refs/heads/main' - uses: actions/upload-artifact@v4.4.0 - with: - name: github-pages - path: ${{ github.workspace }}/github-pages.tar - retention-days: 1 - if-no-files-found: error - - name: Upload artifact for pull request link + - name: Upload artifact for job analysis if: github.event_name == 'pull_request' - id: upload-artifact-pr uses: actions/upload-artifact@v4.4.0 with: name: github-pages-${{ github.sha }} - path: ${{ github.workspace }}/github-pages.tar + path: github-pages.tar retention-days: 1 if-no-files-found: error - - name: Comment artifact URL - if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.fork == false - run: | - gh pr comment ${{ github.event.pull_request.number }} \ - --body "Documentation artifact: ${{ steps.upload-artifact-pr.outputs.artifact-url }}" - env: - GH_TOKEN: ${{ github.token }} docs-deploy: - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} + name: Deploy documentation to GitHub Pages permissions: pages: write id-token: write + contents: write + concurrency: + group: gh-pages + cancel-in-progress: false runs-on: ubuntu-latest - if: github.event_name == 'push' && github.ref == 'refs/heads/main' needs: docs-build steps: - - name: Deploy to GitHub Pages + - name: Download documentation artifact + uses: actions/download-artifact@v4.1.8 + with: + name: github-pages-${{ github.sha }} + - name: Untar documentation artifact + run: tar -xf github-pages.tar + # FIXME: query repository settings instead of blindly trying! + - name: Deploy 🚀 + id: pages-deployment + continue-on-error: true + uses: ./.github/actions/deploy-versioned-pages + with: + source_folder: "." + - name: Deploy (fallback) 🚀 id: deployment + # If the new deployment from gh-pages branch fails, at least deploy the current version. + # This is only a short-term solution, until we can change the repository settings. + if: ${{ steps.pages-deployment.outcome == 'failure' && github.event_name == 'push' && github.ref_name == 'main' }} uses: actions/deploy-pages@v4.0.5