diff --git a/.github/workflows/delete_pr_preview_comment.yml b/.github/workflows/delete_pr_preview_comment.yml deleted file mode 100644 index 5c19a91..0000000 --- a/.github/workflows/delete_pr_preview_comment.yml +++ /dev/null @@ -1,475 +0,0 @@ -# =========== IMPORTANT!! READ THIS!! ============ # -# This file can be copied to be used in other websites deployments. -# When you copy this file, make sure to check and modify the fields -# that here are marked with `MODIFY IF NEEDED`. - -# Other related files/folders that you will also need to copy: -# - .github/workflows/templates/pr_previews_page.html -# - .github/workflows/delete_pr_preview.yml -# ============================================== # - -name: Deploy to GitHub Pages -on: - push: #Action fires anytime there is a push to the following branches - branches: - - main - paths: - - 'documentation/**' # MODIFY IF NEEDED - This should be changed to be DOC_DIR/** based on the env variable DOC_DIR below - pull_request: #Action also fires anytime a PR is (re)opened, closed or synchronized - types: - - opened - - reopened - - synchronize - workflow_dispatch: #Action can also be triggered manually -env: - TZ: Australia/Canberra - DOC_DIR: 'documentation' # MODIFY IF NEEDED - Directory where the mkdocs.yml file is located relative to the repository root - BUILD_DEVELOPMENT_WEBSITE: false # MODIFY IF NEEDED - Set to 'true' to build also the development website from the 'development' branch - BUILD_DIR: ${{ github.workspace }}/website-build - WEBSITE_DIR: ${{ github.workspace }}/full-website - PR_PREVIEWS_DIR: pr-previews - PR_PREVIEW_EXCLUDE_REGEX: ^!no-(pr-)?preview\b # This regex will be considered case insensitive - PR_PREVIEW_COMMENT_LABEL: pr-preview-comment -concurrency: - group: documentation-build-deploy - cancel-in-progress: true - - # ========== You should not need to modify anything below this ============ # - -jobs: - # The conditionals cannot depend directly from the GitHub environment (e.g., if: env.BUILD_DEVELOPMENT_WEBSITE == 'true') - # so we use a job to set that as an output that can be then used in the other jobs' conditionals - set-development-preview-condition: - name: Set development preview build condition - runs-on: ubuntu-latest - outputs: - build_development_website: ${{ steps.set-condition.outputs.build_development_website }} - steps: - - name: Set condition - id: set-condition - run: echo "build_development_website=${{ env.BUILD_DEVELOPMENT_WEBSITE }}" >> $GITHUB_OUTPUT - - # Get the root url to be used at build time to set the SITE_URL env variable - # used in the mkdocs.yml file to construct the website map for links - get-root-url: - name: Set root URL - runs-on: ubuntu-latest - outputs: - root_url: ${{ steps.get-root-url.outputs.root_url }} - env: - GH_TOKEN: ${{ github.token }} # Required for gh usage - steps: - - name: Get root url - id: get-root-url - run: | - root_url=$(gh api repos/${{ github.repository }}/pages --jq '.html_url') - if [[ $? != 0 ]]; then - echo "::error::The repository '${{ github.repository }}' does not seem to gave a GitHub Pages deployment." - exit 1 - fi - echo "Root url set to '${root_url}'" - echo "root_url=${root_url}" >> $GITHUB_OUTPUT - - # Get the date to be used in the PR preview comments - get-date: - name: Get date - runs-on: ubuntu-latest - # Run this job also if the workflow was skipped for concurrency reasons - if: ${{ always() }} - env: - TZ: Australia/Canberra - outputs: - date: ${{ steps.get-date.outputs.date }} - steps: - - name: Get date - id: get-date - run: echo "date=$(date '+%Y-%m-%d %H:%M %Z')" >> $GITHUB_OUTPUT - - # Set up the PR preview comment - pr-preview-setup: - name: PR preview setup - # Run this job also if the workflow was skipped for concurrency reasons but only - # if the action was fired because of a PR - if: ${{ always() && github.event_name == 'pull_request' }} - needs: get-date - runs-on: ubuntu-latest - env: - HEAD: ${{ github.event.pull_request.head.sha }} - HEAD_URL: https://github.com/${{ github.event.pull_request.head.repo.full_name }}/commit/${{ github.event.pull_request.head.sha }} - permissions: - pull-requests: write - steps: - - name: Add PR preview setup comment - if: ${{ github.event.action != 'closed' }} - uses: access-nri/actions/.github/actions/comment@main - with: - message: | - PR Preview - :---: - 🛫 The preview of PR head commit [${{ env.HEAD }}](${{ env.HEAD_URL }}) is currently being deployed.
The preview URL will be available once the deployment completes.
For further details, please check the [Actions](https://github.com/${{ github.repository }}/actions) tab. - ${{ needs.get-date.outputs.date }} - label: ${{ env.PR_PREVIEW_COMMENT_LABEL }} - -# Build the main website - build-main: - name: Build main website - runs-on: ubuntu-latest - needs: get-root-url - env: - GH_TOKEN: ${{ github.token }} # Required for gh usage - steps: - - name: Checkout - uses: actions/checkout@v4 - with: - ref: main - - - name: Check mkdocs.yaml - id: check-mkdocs - working-directory: ${{ env.DOC_DIR }} - run: | - if [[ -f mkdocs.yml ]]; then - echo "mkdocs.yml file found." - else - echo "::warning::No mkdocs.yml file found in '$(git rev-parse --abbrev-ref HEAD)'." - echo "SKIP_STEP=true" >> $GITHUB_ENV - fi - - - name: Python setup - uses: actions/setup-python@v5 - if: ${{ ! env.SKIP_STEP }} - with: - python-version: 3.11.x - - - name: Install dependencies - working-directory: ${{ env.DOC_DIR }} - if: ${{ ! env.SKIP_STEP }} - run: | - pip install -r requirements.txt - - - name: Build website - working-directory: ${{ env.DOC_DIR }} - env: - GH_TOKEN: ${{ github.token }} # Required for gh usage - ROOT_URL: ${{ needs.get-root-url.outputs.root_url }} - id: build - if: ${{ ! env.SKIP_STEP }} - run: | - dir= - site_url="${{ env.ROOT_URL }}${dir:+${dir}/}" - command="SITE_URL=${site_url} mkdocs build -f mkdocs.yml -d ${{env.BUILD_DIR}}" - echo "$command" - eval "$command" - - - name: Upload artifact - uses: actions/upload-artifact@v4 - if: ${{ ! env.SKIP_STEP }} - with: - name: main-website - path: ${{env.BUILD_DIR}} - -# Build the development website - build-development: - name: Build development website - runs-on: ubuntu-latest - needs: [set-development-preview-condition,get-root-url] - if: ${{ needs.set-development-preview-condition.outputs.build_development_website == 'true' }} - env: - GH_TOKEN: ${{ github.token }} # Required for gh usage - steps: - - name: Checkout - uses: actions/checkout@v4 - with: - ref: development - - - name: Check mkdocs.yaml - id: check-mkdocs - run: | - if [[ -f mkdocs.yml ]]; then - echo "mkdocs.yml file found." - else - echo "::warning::No mkdocs.yml file found in '$(git rev-parse --abbrev-ref HEAD)'." - echo "SKIP_STEP=true" >> $GITHUB_ENV - fi - - - name: Python setup - uses: actions/setup-python@v5 - if: ${{ ! env.SKIP_STEP }} - with: - python-version: 3.11.x - - - name: Install dependencies - working-directory: ${{ env.DOC_DIR }} - if: ${{ ! env.SKIP_STEP }} - run: | - pip install -r requirements.txt - - - name: Build website - working-directory: ${{ env.DOC_DIR }} - env: - GH_TOKEN: ${{ github.token }} # Required for gh usage - ROOT_URL: ${{ needs.get-root-url.outputs.root_url }} - id: build - if: ${{ ! env.SKIP_STEP }} - run: | - dir=development-website - site_url="${{ env.ROOT_URL }}${dir:+${dir}/}" - command="SITE_URL=${site_url} mkdocs build -f mkdocs.yml -d ${{env.BUILD_DIR}}" - echo "$command" - eval "$command" - - - name: Upload artifact - uses: actions/upload-artifact@v4 - if: ${{ ! env.SKIP_STEP }} - with: - name: development-website - path: ${{env.BUILD_DIR}} - - # Get information about open PRs to be used to build websites - # for the PR previews and to setup the PR-previews comments - get-prs-info: - name: Get PRs info - runs-on: ubuntu-latest - needs: get-root-url - outputs: - open_prs_info: ${{ steps.get-prs-info.outputs.open_prs_info }} - env: - GH_TOKEN: ${{ github.token }} # Required for gh usage - ROOT_URL: ${{ needs.get-root-url.outputs.root_url }} - steps: - - name: Checkout - uses: actions/checkout@v4 - - - name: Get PRs info - id: get-prs-info - working-directory: ${{ env.DOC_DIR }} - run: | - # Include only open PRs, not from forks, and whose head branch is not `main` - open_prs=$( - gh pr list \ - --state open \ - --json number,title,headRepositoryOwner,headRefOid,body \ - --jq 'sort_by(.number) | .[] | select( .headRefName!="main" and .headRepositoryOwner.login=="ACCESS-NRI")' \ - ) - - # If open PRs are found, filter them and output the desired json object - if [[ -n "$open_prs" ]]; then - # Keep only PRs: - # - with a mkdocs.yml file in their head commit - # - whose body doesn't start with a PR_PREVIEW_EXCLUDE_REGEX line - filtered_prs=$( - while IFS= read -r pr; do - sha=$(jq -r '.headRefOid' <<< $pr) - body=$(jq -r '.body' <<< $pr) - if ( - gh api repos/${{ github.repository }}/git/trees/${sha}?recursive=1 | \ - jq '.tree[].path' | grep 'mkdocs.ya\?ml' > /dev/null - ) && ( - ! grep -qi '${{ env.PR_PREVIEW_EXCLUDE_REGEX }}' <<< "$body" - ); then - echo $pr - fi - done <<< "$open_prs" - ) - - # Define the PR info json object with the following fields: - # - pr_number: the PR number - # - pr_title: the PR title - # - pr_head_sha: the PR head commit sha - # - pr_preview_url: the PR preview URL - open_prs_info=$( - jq -s -c '[.[] | { - pr_number: .number, - pr_title: .title, - pr_head_sha: .headRefOid, - pr_preview_url: ("${{ env.ROOT_URL }}${{ env.PR_PREVIEWS_DIR }}/" + (.number | tostring)) - }]' <<< "$filtered_prs" - ) - - echo "Found the following open PRs:" - jq <<< "$open_prs_info" - else - echo "No open PRs found." - fi - echo "open_prs_info=${open_prs_info}" >> "$GITHUB_OUTPUT" - -# Build each pr website with matrix strategy jobs - build-pr: - name: Build PR ${{matrix.pr_number}} - runs-on: ubuntu-latest - needs: [get-root-url, get-prs-info] - # Run this job only if there are open PRs - if: ${{ needs.get-prs-info.outputs.open_prs_info != '' }} - env: - GH_TOKEN: ${{ github.token }} # Required for gh usage - strategy: - fail-fast: true - matrix: - include: ${{ fromJson(needs.get-prs-info.outputs.open_prs_info) }} - steps: - - name: Checkout - uses: actions/checkout@v4 - with: - ref: ${{ matrix.pr_head_sha }} - - - name: Python setup - uses: actions/setup-python@v5 - with: - python-version: 3.11.x - - - name: Install dependencies - working-directory: ${{ env.DOC_DIR }} - run: | - pip install -r requirements.txt - - - name: Build website - working-directory: ${{ env.DOC_DIR }} - env: - GH_TOKEN: ${{ github.token }} # Required for gh usage - ROOT_URL: ${{ needs.get-root-url.outputs.root_url }} - id: build - run: | - dir=$(sed 's|^${{ env.ROOT_URL }}||' <<< ${{ matrix.pr_preview_url }}) - site_url="${{ env.ROOT_URL }}${dir:+${dir}/}" - command="SITE_URL=${site_url} mkdocs build -f mkdocs.yml -d ${{env.BUILD_DIR}}" - echo "$command" - eval "$command" - - - name: Upload artifact - uses: actions/upload-artifact@v4 - with: - name: ${{ matrix.pr_number }} - path: ${{env.BUILD_DIR}} - - # Create the pr-previews page with links to all avaiable pr-previews - create-pr-previews-page: - name: Create PR previews list page - runs-on: ubuntu-latest - needs: [get-root-url, get-prs-info] - env: - GH_TOKEN: ${{ github.token }} # Required for gh usage - FILE_NAME: index.html - steps: - - name: Checkout - uses: actions/checkout@v4 - - - name: Python setup - uses: actions/setup-python@v5 - with: - python-version: 3.11.x - - - name: Install dependencies - run: pip install jinja-cli==1.2.2 - - - name: Create PR previews page - run: | - open_prs_json='${{ needs.get-prs-info.outputs.open_prs_info }}' - if [[ -z "$open_prs_json" ]]; then - data_json=$(jq -c -n --argjson data "$open_prs_json" '{"data": $data}') - else - data_json='{}' - fi - jq -c <<< "$data_json" | \ - jinja -d - -f json ./.github/workflows/templates/pr_previews_page.html > ${{ env.FILE_NAME }} - echo "Created the pr-previews page through the following html file:" - cat ${{ env.FILE_NAME }} - - - name: Upload artifact - uses: actions/upload-artifact@v4 - with: - name: '${{ env.PR_PREVIEWS_DIR }}' - path: ${{ env.FILE_NAME }} - -# Set the final website structure for the deployment - set-website-structure: - name: Set entire website structure - runs-on: ubuntu-latest - needs: [build-main, build-development, build-pr, create-pr-previews-page] - # Run this job also if build-pr or build-development was skipped (no PR was found or no development build requested) - if: ${{ always() && contains(fromJson('["success","skipped"]'), needs.build-pr.result) && contains(fromJson('["success","skipped"]'), needs.build-development.result) }} - env: - GH_TOKEN: ${{ github.token }} # Required for gh usage - steps: - - name: Checkout - uses: actions/checkout@v4 - - - name: Download all build artifacts - uses: actions/download-artifact@v4 - with: - path: ${{ env.WEBSITE_DIR }} - - - name: Set website structure - run: | - # Move all PR websites (directories named with only numbers) within the pr-previews directory - # Using '[0-9]*' instead of '[0-9]+' within the regex because I cannot make the plus ('+') sign to be recognised correctly - find ${{ env.WEBSITE_DIR }} -maxdepth 1 -type d -regex '.*/[0-9]*$' -exec mv {} ${{ env.WEBSITE_DIR }}/${{ env.PR_PREVIEWS_DIR }} \; - # Move the main website to the root of the website directory and remove the empty main-website artifact directory - mv ${{ env.WEBSITE_DIR }}/main-website/* ${{ env.WEBSITE_DIR }} - rm -rf ${{ env.WEBSITE_DIR }}/main-website - # Set permissions - chmod -c -R +rX ${{ env.WEBSITE_DIR }} - echo "Website structure set to:" - tree -d -L 2 ${{ env.WEBSITE_DIR }} - - - name: Create artifact for deployment to GitHub Pages - uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa #v3.0.1 - with: - path: ${{ env.WEBSITE_DIR }} - - # Deploy the website to GitHub Pages - deploy: - needs: set-website-structure - runs-on: ubuntu-latest - # Need to specify this conition because otherwise this job might be skipped if - # any job needed by this job's needed job(s) is skipped (e.g., if a job needed by set-website-structure is skipped) - # Reference: https://github.com/actions/runner/issues/2205 - if: ${{ always() && ! failure() }} - permissions: - pages: write # to deploy to Pages - id-token: write # to verify the deployment originates from an appropriate source - steps: - - name: Deploy to GitHub Pages - uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e #v4.0.5 - - # Set pr-preview messages - pr-preview: - needs: [get-date, get-prs-info, deploy] - # Run this job only if there are open PRs - if: ${{ always() && ! failure() && needs.get-prs-info.outputs.open_prs_info != '' }} - runs-on: ubuntu-latest - strategy: - fail-fast: false - matrix: - include: ${{ fromJson(needs.get-prs-info.outputs.open_prs_info) }} - permissions: - pull-requests: write - steps: - - name: Add PR preview setup comment - uses: access-nri/actions/.github/actions/comment@main - with: - message: | - PR Preview - :---: - 🚀 Preview of PR head commit ${{ matrix.pr_head_sha }} deployed to ${{ matrix.pr_preview_url }} - ${{ needs.get-date.outputs.date }} - Preview generated through the _${{ github.workflow }}_ workflow run [${{ github.run_id }}](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}). - number: ${{ matrix.pr_number }} - label: ${{ env.PR_PREVIEW_COMMENT_LABEL }} - - failed-preview: - needs: [get-date, pr-preview] - # Run this job if the workflow was triggered because of a pull request and any previou job failed - if: ${{ github.event_name == 'pull_request' && failure() }} - runs-on: ubuntu-latest - permissions: - pull-requests: write - steps: - - name: Add PR preview failure comment - uses: access-nri/actions/.github/actions/comment@main - with: - message: | - PR Preview - :---: - ⚠️ There was an error in the pr-preview deployment. - For more information check the [Actions](https://github.com/${{github.repository}}/actions) tab. - ${{ needs.get-date.outputs.date }} - label: ${{ env.PR_PREVIEW_COMMENT_LABEL }} \ No newline at end of file diff --git a/.github/workflows/deploy_to_github_pages.yml b/.github/workflows/deploy_to_github_pages.yml deleted file mode 100644 index 9584176..0000000 --- a/.github/workflows/deploy_to_github_pages.yml +++ /dev/null @@ -1,458 +0,0 @@ -name: Deploy to GitHub Pages -on: - push: #Action fires anytime there is a push to the following branches - branches: - - main - - development - paths: - - 'documentation/**' - pull_request: #Action also fires anytime a PR is (re)opened, closed or synchronized - types: - - opened - - reopened - - synchronize - workflow_dispatch: #Action can also be triggered manually -env: - TZ: Australia/Canberra - DOC_DIR: 'documentation' - BUILD_DIR: ${{ github.workspace }}/website-build - WEBSITE_DIR: ${{ github.workspace }}/full-website - PR_PREVIEWS_DIR: pr-previews - PR_PREVIEW_EXCLUDE_REGEX: ^!no-(pr-)?preview\b - PR_PREVIEW_COMMENT_LABEL: pr-preview-comment - BUILD_DEVELOPMENT_WEBSITE: false -concurrency: - group: documentation-build-deploy - cancel-in-progress: true - -jobs: - # The conditionals cannot depend directly from the GitHub environment (e.g., if: env.BUILD_DEVELOPMENT_WEBSITE == 'true') - # so we use a job to set that as an output that can be then used in the other jobs' conditionals - set-development-preview-condition: - name: Set development preview build condition - runs-on: ubuntu-latest - outputs: - build_development_website: ${{ steps.set-condition.outputs.build_development_website }} - steps: - - name: Set condition - id: set-condition - run: echo "build_development_website=${{ env.BUILD_DEVELOPMENT_WEBSITE }}" >> $GITHUB_OUTPUT - - # Get the root url to be used at build time to set the SITE_URL env variable - # used in the mkdocs.yml file to construct the website map for links - get-root-url: - name: Set root URL - runs-on: ubuntu-latest - outputs: - root_url: ${{ steps.get-root-url.outputs.root_url }} - env: - GH_TOKEN: ${{ github.token }} # Required for gh usage - steps: - - name: Get root url - id: get-root-url - run: | - root_url=$(gh api repos/${{ github.repository }}/pages --jq '.html_url') - if [[ $? != 0 ]]; then - echo "::error::The repository '${{ github.repository }}' does not seem to gave a GitHub Pages deployment." - exit 1 - fi - echo "Root url set to '${root_url}'" - echo "root_url=${root_url}" >> $GITHUB_OUTPUT - - # Get the date to be used in the PR preview comments - get-date: - name: Get date - runs-on: ubuntu-latest - # Run this job also if the workflow was skipped for concurrency reasons - if: ${{ always() }} - env: - TZ: Australia/Canberra - outputs: - date: ${{ steps.get-date.outputs.date }} - steps: - - name: Get date - id: get-date - run: echo "date=$(date '+%Y-%m-%d %H:%M %Z')" >> $GITHUB_OUTPUT - - # Set up the PR preview comment - pr-preview-setup: - name: PR preview setup - # Run this job also if the workflow was skipped for concurrency reasons but only - # if the action was fired because of a PR - if: ${{ always() && github.event_name == 'pull_request' }} - needs: get-date - runs-on: ubuntu-latest - env: - HEAD: ${{ github.event.pull_request.head.sha }} - HEAD_URL: https://github.com/${{ github.event.pull_request.head.repo.full_name }}/commit/${{ github.event.pull_request.head.sha }} - permissions: - pull-requests: write - steps: - - name: Add PR preview setup comment - if: ${{ github.event.action != 'closed' }} - uses: access-nri/actions/.github/actions/comment@main - with: - message: | - PR Preview - :---: - 🛫 The preview of PR head commit [${{ env.HEAD }}](${{ env.HEAD_URL }}) is currently being deployed.
The preview URL will be available once the deployment completes.
For further details, please check the [Actions](https://github.com/${{ github.repository }}/actions) tab. - ${{ needs.get-date.outputs.date }} - label: ${{ env.PR_PREVIEW_COMMENT_LABEL }} - -# Build the main website - build-main: - name: Build main website - runs-on: ubuntu-latest - needs: get-root-url - env: - GH_TOKEN: ${{ github.token }} # Required for gh usage - steps: - - name: Checkout - uses: actions/checkout@v4 - with: - ref: main - - - name: Check mkdocs.yaml - id: check-mkdocs - working-directory: ${{ env.DOC_DIR }} - run: | - if [[ -f mkdocs.yml ]]; then - echo "mkdocs.yml file found." - else - echo "::warning::No mkdocs.yml file found in '$(git rev-parse --abbrev-ref HEAD)'." - echo "SKIP_STEP=true" >> $GITHUB_ENV - fi - - - name: Python setup - uses: actions/setup-python@v5 - if: ${{ ! env.SKIP_STEP }} - with: - python-version: 3.11.x - - - name: Install dependencies - working-directory: ${{ env.DOC_DIR }} - if: ${{ ! env.SKIP_STEP }} - run: | - pip install -r requirements.txt - - - name: Build website - working-directory: ${{ env.DOC_DIR }} - env: - GH_TOKEN: ${{ github.token }} # Required for gh usage - ROOT_URL: ${{ needs.get-root-url.outputs.root_url }} - id: build - if: ${{ ! env.SKIP_STEP }} - run: | - dir= - site_url="${{ env.ROOT_URL }}${dir:+${dir}/}" - command="SITE_URL=${site_url} mkdocs build -f mkdocs.yml -d ${{env.BUILD_DIR}}" - echo "$command" - eval "$command" - - - name: Upload artifact - uses: actions/upload-artifact@v4 - if: ${{ ! env.SKIP_STEP }} - with: - name: main-website - path: ${{env.BUILD_DIR}} - -# Build the development website - build-development: - name: Build development website - runs-on: ubuntu-latest - needs: [set-development-preview-condition,get-root-url] - if: ${{ needs.set-development-preview-condition.outputs.build_development_website == 'true' }} - env: - GH_TOKEN: ${{ github.token }} # Required for gh usage - steps: - - name: Checkout - uses: actions/checkout@v4 - with: - ref: development - - - name: Check mkdocs.yaml - id: check-mkdocs - run: | - if [[ -f mkdocs.yml ]]; then - echo "mkdocs.yml file found." - else - echo "::warning::No mkdocs.yml file found in '$(git rev-parse --abbrev-ref HEAD)'." - echo "SKIP_STEP=true" >> $GITHUB_ENV - fi - - - name: Python setup - uses: actions/setup-python@v5 - if: ${{ ! env.SKIP_STEP }} - with: - python-version: 3.11.x - - - name: Install dependencies - working-directory: ${{ env.DOC_DIR }} - if: ${{ ! env.SKIP_STEP }} - run: | - pip install -r requirements.txt - - - name: Build website - working-directory: ${{ env.DOC_DIR }} - env: - GH_TOKEN: ${{ github.token }} # Required for gh usage - ROOT_URL: ${{ needs.get-root-url.outputs.root_url }} - id: build - if: ${{ ! env.SKIP_STEP }} - run: | - dir=development-website - site_url="${{ env.ROOT_URL }}${dir:+${dir}/}" - command="SITE_URL=${site_url} mkdocs build -f mkdocs.yml -d ${{env.BUILD_DIR}}" - echo "$command" - eval "$command" - - - name: Upload artifact - uses: actions/upload-artifact@v4 - if: ${{ ! env.SKIP_STEP }} - with: - name: development-website - path: ${{env.BUILD_DIR}} - - # Get information about open PRs to be used to build websites - # for the PR previews and to setup the PR-previews comments - get-prs-info: - name: Get PRs info - runs-on: ubuntu-latest - needs: get-root-url - outputs: - open_prs_info: ${{ steps.get-prs-info.outputs.open_prs_info }} - env: - GH_TOKEN: ${{ github.token }} # Required for gh usage - ROOT_URL: ${{ needs.get-root-url.outputs.root_url }} - steps: - - name: Checkout - uses: actions/checkout@v4 - - - name: Get PRs info - id: get-prs-info - working-directory: ${{ env.DOC_DIR }} - run: | - # Include only open PRs, not from forks, and whose head branch is not `main` - open_prs=$( - gh pr list \ - --state open \ - --json number,title,headRepositoryOwner,headRefOid,body \ - --jq 'sort_by(.number) | .[] | select( .headRefName!="main" and .headRepositoryOwner.login=="ACCESS-NRI")' \ - ) - - # If open PRs are found, filter them and output the desired json object - if [[ -n "$open_prs" ]]; then - # Keep only PRs: - # - with a mkdocs.yml file in their head commit - # - whose body doesn't start with a PR_PREVIEW_EXCLUDE_REGEX line - filtered_prs=$( - while IFS= read -r pr; do - sha=$(jq -r '.headRefOid' <<< $pr) - body=$(jq -r '.body' <<< $pr) - if ( - gh api repos/${{ github.repository }}/git/trees/${sha}?recursive=1 | \ - jq '.tree[].path' | grep 'mkdocs.ya\?ml' > /dev/null - ) && ( - ! grep -qi '${{ env.PR_PREVIEW_EXCLUDE_REGEX }}' <<< "$body" - ); then - echo $pr - fi - done <<< "$open_prs" - ) - - # Define the PR info json object with the following fields: - # - pr_number: the PR number - # - pr_title: the PR title - # - pr_head_sha: the PR head commit sha - # - pr_preview_url: the PR preview URL - open_prs_info=$( - jq -s -c '[.[] | { - pr_number: .number, - pr_title: .title, - pr_head_sha: .headRefOid, - pr_preview_url: ("${{ env.ROOT_URL }}${{ env.PR_PREVIEWS_DIR }}/" + (.number | tostring)) - }]' <<< "$filtered_prs" - ) - - echo "Found the following open PRs:" - jq <<< "$open_prs_info" - else - echo "No open PRs found." - fi - echo "open_prs_info=${open_prs_info}" >> "$GITHUB_OUTPUT" - -# Build each pr website with matrix strategy jobs - build-pr: - name: Build PR ${{matrix.pr_number}} - runs-on: ubuntu-latest - needs: [get-root-url, get-prs-info] - # Run this job only if there are open PRs - if: ${{ needs.get-prs-info.outputs.open_prs_info != '' }} - env: - GH_TOKEN: ${{ github.token }} # Required for gh usage - strategy: - fail-fast: true - matrix: - include: ${{ fromJson(needs.get-prs-info.outputs.open_prs_info) }} - steps: - - name: Checkout - uses: actions/checkout@v4 - with: - ref: ${{ matrix.pr_head_sha }} - - - name: Python setup - uses: actions/setup-python@v5 - with: - python-version: 3.11.x - - - name: Install dependencies - working-directory: ${{ env.DOC_DIR }} - run: | - pip install -r requirements.txt - - - name: Build website - working-directory: ${{ env.DOC_DIR }} - env: - GH_TOKEN: ${{ github.token }} # Required for gh usage - ROOT_URL: ${{ needs.get-root-url.outputs.root_url }} - id: build - run: | - dir=$(sed 's|^${{ env.ROOT_URL }}||' <<< ${{ matrix.pr_preview_url }}) - site_url="${{ env.ROOT_URL }}${dir:+${dir}/}" - command="SITE_URL=${site_url} mkdocs build -f mkdocs.yml -d ${{env.BUILD_DIR}}" - echo "$command" - eval "$command" - - - name: Upload artifact - uses: actions/upload-artifact@v4 - with: - name: ${{ matrix.pr_number }} - path: ${{env.BUILD_DIR}} - - # Create the pr-previews page with links to all avaiable pr-previews - create-pr-previews-page: - name: Create PR previews list page - runs-on: ubuntu-latest - needs: [get-root-url, get-prs-info] - env: - GH_TOKEN: ${{ github.token }} # Required for gh usage - FILE_NAME: index.html - steps: - - name: Checkout - uses: actions/checkout@v4 - - - name: Python setup - uses: actions/setup-python@v5 - with: - python-version: 3.11.x - - - name: Install dependencies - run: pip install jinja-cli==1.2.2 - - - name: Create PR previews page - run: | - printf '{"data": %s}' '${{ needs.get-prs-info.outputs.open_prs_info }}' | \ - jinja -d - -f json ./.github/workflows/templates/pr_previews_page.html > ${{ env.FILE_NAME }} - echo "Created the pr-previews page through the following html file:" - cat ${{ env.FILE_NAME }} - - - name: Upload artifact - uses: actions/upload-artifact@v4 - with: - name: '${{ env.PR_PREVIEWS_DIR }}' - path: ${{ env.FILE_NAME }} - -# Set the final website structure for the deployment - set-website-structure: - name: Set entire website structure - runs-on: ubuntu-latest - needs: [build-main, build-development, build-pr, create-pr-previews-page] - # Run this job also if build-pr or build-development was skipped (no PR was found or no development build requested) - if: ${{ always() && contains(fromJson('["success","skipped"]'), needs.build-pr.result) && contains(fromJson('["success","skipped"]'), needs.build-development.result) }} - env: - GH_TOKEN: ${{ github.token }} # Required for gh usage - steps: - - name: Checkout - uses: actions/checkout@v4 - - - name: Download all build artifacts - uses: actions/download-artifact@v4 - with: - path: ${{ env.WEBSITE_DIR }} - - - name: Set website structure - run: | - # Move all PR websites (directories named with only numbers) within the pr-previews directory - # Using '[0-9]*' instead of '[0-9]+' within the regex because I cannot make the plus ('+') sign to be recognised correctly - find ${{ env.WEBSITE_DIR }} -maxdepth 1 -type d -regex '.*/[0-9]*$' -exec mv {} ${{ env.WEBSITE_DIR }}/${{ env.PR_PREVIEWS_DIR }} \; - # Move the main website to the root of the website directory and remove the empty main-website artifact directory - mv ${{ env.WEBSITE_DIR }}/main-website/* ${{ env.WEBSITE_DIR }} - rm -rf ${{ env.WEBSITE_DIR }}/main-website - # Set permissions - chmod -c -R +rX ${{ env.WEBSITE_DIR }} - echo "Website structure set to:" - tree -d -L 2 ${{ env.WEBSITE_DIR }} - - - name: Create artifact for deployment to GitHub Pages - uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa #v3.0.1 - with: - path: ${{ env.WEBSITE_DIR }} - - # Deploy the website to GitHub Pages - deploy: - needs: set-website-structure - runs-on: ubuntu-latest - # Need to specify this conition because otherwise this job might be skipped if - # any job needed by this job's needed job(s) is skipped (e.g., if a job needed by set-website-structure is skipped) - # Reference: https://github.com/actions/runner/issues/2205 - if: ${{ always() && ! failure() }} - permissions: - pages: write # to deploy to Pages - id-token: write # to verify the deployment originates from an appropriate source - steps: - - name: Deploy to GitHub Pages - uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e #v4.0.5 - - # Set pr-preview messages - pr-preview: - needs: [get-date, get-prs-info, deploy] - # Run this job only if there are open PRs - if: ${{ always() && ! failure() && needs.get-prs-info.outputs.open_prs_info != '' }} - runs-on: ubuntu-latest - strategy: - fail-fast: false - matrix: - include: ${{ fromJson(needs.get-prs-info.outputs.open_prs_info) }} - permissions: - pull-requests: write - steps: - - name: Add PR preview setup comment - uses: access-nri/actions/.github/actions/comment@main - with: - message: | - PR Preview - :---: - 🚀 Preview of PR head commit ${{ matrix.pr_head_sha }} deployed to ${{ matrix.pr_preview_url }} - ${{ needs.get-date.outputs.date }} - Preview generated through the _${{ github.workflow }}_ workflow run [${{ github.run_id }}](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}). - number: ${{ matrix.pr_number }} - label: ${{ env.PR_PREVIEW_COMMENT_LABEL }} - - failed-preview: - needs: [get-date, pr-preview] - # Run this job if the workflow was triggered because of a pull request and any previou job failed - if: ${{ github.event_name == 'pull_request' && failure() }} - runs-on: ubuntu-latest - permissions: - pull-requests: write - steps: - - name: Add PR preview failure comment - uses: access-nri/actions/.github/actions/comment@main - with: - message: | - PR Preview - :---: - ⚠️ There was an error in the pr-preview deployment. - For more information check the [Actions](https://github.com/${{github.repository}}/actions) tab. - ${{ needs.get-date.outputs.date }} - label: ${{ env.PR_PREVIEW_COMMENT_LABEL }} \ No newline at end of file diff --git a/.github/workflows/templates/pr_previews_page.html b/.github/workflows/templates/pr_previews_page.html deleted file mode 100644 index 301c611..0000000 --- a/.github/workflows/templates/pr_previews_page.html +++ /dev/null @@ -1,34 +0,0 @@ - - - - - -

PR Previews

- - - \ No newline at end of file diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..447240d --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,36 @@ +# =========== IMPORTANT!! READ THIS!! ============ # +# This file can be copied to be used for websites deployments with RTD. +# When you copy this file, make sure to check and modify the fields +# that here are marked with `MODIFY IF NEEDED`. + +# The post_build job in this file checks links using ACCESS-Hive-Docs check_links_workflow +# (https://github.com/ACCESS-NRI/ACCESS-Hive-Docs/blob/main/.github/workflows/check_links_workflow.yml) +# By default this uses the ACCESS-Hive-Docs lychee config (https://github.com/ACCESS-NRI/ACCESS-Hive-Docs/blob/main/.github/workflows/lychee_config.toml) +# To use a custom lychee config, add `.github/workflows/lychee_config.toml` to this repo. +# ============================================== # + + +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# ReadtheDocs config version +version: 2 + +# Set the ReadtheDocs Docker image OS, Python version, and other tools you might need +build: + os: ubuntu-24.04 + tools: + python: "3.13" + # jobs: + # post_checkout: # MODIFY IF NEEDED: uncomment to cancel the RTD build + # - exit 183 + +# Build documentation with Mkdocs +mkdocs: + configuration: documentation/mkdocs.yml # MODIFY IF NEEDED: path to mkdocs.yml + +# Python requirements to build your documentation +# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html +python: + install: + - requirements: documentation/requirements.txt # MODIFY IF NEEDED: path to requirements.txt \ No newline at end of file