esm1.6 configuration documentation

.github/workflows/deploy_to_github_pages.yml

@@ -0,0 +1,238 @@
+name: Deploy to GitHub Pages
+on:
+  push: #Action fires anytime there is a push to the following branches
+    branches:
+      - main
+    paths:
+      - documentation/**
+  pull_request: #Action also fires anytime a PR is (re)opened, closed or synchronized
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - closed
+    paths:
+      - documentation/**
+  workflow_dispatch: #Action can also be triggered manually
+env:
+  TZ: Australia/Canberra
+  DOC_DIR: documentation
+  ROOT_BUILD_DIR: ${{ github.workspace }}/website
+  COMMENT_LABEL: pr-preview
+  ROOT_DOMAIN: https://access-nri.github.io
+
+jobs:
+  set-root-url:
+    runs-on: ubuntu-latest
+    outputs:
+      root_url: ${{ steps.set-root-url.outputs.root_url }}
+    steps:
+      - name: Set root url
+        id: set-root-url
+        run: |
+          if [[ ${{ env.ROOT_DOMAIN }} == https://access-nri.github.io ]]; then
+            root_url=${{ env.ROOT_DOMAIN }}/${{ github.event.repository.name }}
+          else
+            root_url=${{ env.ROOT_DOMAIN }}
+          fi
+          echo "Root url set to ${root_url}"
+          echo "root_url=${root_url}" >> $GITHUB_OUTPUT
+
+  get-date:
+    runs-on: ubuntu-latest
+    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
+
+  pr-preview-setup:
+    # Run this job only if the action was fired because of a PR
+    if: ${{ 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 commit [${{ env.HEAD }}](${{ env.HEAD_URL }}) is currently being deployed.<br>The preview URL will be available once the deployment completes.<br>For further details, please check the [Actions](https://github.com/${{ github.repository }}/actions) tab.
+           ${{ needs.get-date.outputs.date }}
+          label: ${{ env.COMMENT_LABEL }}
+
+      - name: Remove PR preview comment
+        if: ${{ github.event.action == 'closed' }}
+        uses: access-nri/actions/.github/actions/comment@main
+        with:
+          delete: true
+          label: ${{ env.COMMENT_LABEL }}
+
+  build:
+    # Cancel any previous build/deploy jobs that are still running (no need to build/deploy multiple times)
+    concurrency:
+      group: documentation-build-deploy
+      cancel-in-progress: true
+    runs-on: ubuntu-latest
+    needs: set-root-url
+    outputs:
+      matrix_include: ${{ steps.build-pr-preview.outputs.matrix_include }}
+    if: ${{ ! ( github.event_name == 'pull_request' && github.event.action == 'closed' ) }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - 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 main website
+        working-directory: ${{ env.DOC_DIR }}
+        env:
+          GH_TOKEN: ${{ github.token }} # Required for gh usage
+          ROOT_URL: ${{ needs.set-root-url.outputs.root_url }}
+        run: |
+          echo "::group::Build main website"
+          git fetch origin main
+          git checkout main
+          if [[ -f mkdocs.yml ]]; then
+            dir=
+            site_url=${{ env.ROOT_URL }}/${dir}
+            build_dir=${{ env.ROOT_BUILD_DIR }}/${dir}
+            command="SITE_URL=${site_url} mkdocs build -f mkdocs.yml -d ${build_dir}"
+            echo "$command"
+            eval "$command"
+          else
+            echo "::warning::No configuration found in the 'main' branch."
+          fi
+          echo "::endgroup::"
+
+      - name: Build PR previews
+        working-directory: ${{ env.DOC_DIR }}
+        env:
+          GH_TOKEN: ${{ github.token }} # Required for gh usage
+          ROOT_URL: ${{ needs.set-root-url.outputs.root_url }}
+        id: build-pr-preview
+        run: |
+          echo "::group::Build PR previews"
+          git fetch --all -Pp
+          # Include only open PRs, not from forks, and whose head branch is not `main`
+          open_pr_info=$(gh pr list \
+            --state open \
+            --json headRepositoryOwner,headRefOid,number,headRefName \
+            --jq '.[] | select( .headRefName!="main" and .headRepositoryOwner.login=="ACCESS-NRI")' \
+          )
+          pr_nums=($(jq '.number' <<< "$open_pr_info"))
+          if [[ -n $pr_nums ]]; then
+            echo "Found the following open PRs: $(IFS=, ; echo "${pr_nums[*]}")."
+            for num in ${pr_nums[@]}; do
+              echo "::group::Build PR preview for PR #${num}"
+              gh pr checkout $num
+              if [[ -f mkdocs.yml ]]; then
+                dir=pr-preview-${num}
+                site_url=${{ env.ROOT_URL }}/${dir}
+                build_dir=${{ env.ROOT_BUILD_DIR }}/${dir}
+                command="SITE_URL=${site_url} mkdocs build -f mkdocs.yml -d ${build_dir}"
+                echo "$command"
+                eval "$command"
+                # Defining the json string for the matrix.include field used in the pr-preview job
+                # Defining the following fields:
+                # - pr_num: the PR number
+                # - pr_preview_url: the URL of the PR preview
+                # - pr_head_sha: the SHA of the commit in the PR head
+                json_array+=("{\"pr_num\":${num},\"pr_preview_url\":\"${site_url}\",\"pr_head_sha\":\"$(git rev-parse HEAD)\"}")
+              else
+                echo "::warning::No configuration found in the PR #${num} head."
+              fi
+              echo '::endgroup::'
+            done
+            # Create the json for the matrix.include from the json_array
+            matrix_include=$(jq -c <<< "[$(IFS=, ; echo "${json_array[*]}")]")
+            echo "matrix_include=${matrix_include}" >> "$GITHUB_OUTPUT"
+          else
+            echo "No open PR found."
+          fi
+          echo '::endgroup::'
+
+      - name: Set permissions
+        run: chmod -c -R +rX ${{ env.ROOT_BUILD_DIR }}
+
+      - name: Create artifact for deployment to GitHub Pages
+        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa #v3.0.1
+        with:
+          path: ${{ env.ROOT_BUILD_DIR }}
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    # Cancel any previous build/deploy jobs that are still running (no need to build/deploy multiple times)
+    concurrency:
+      group: documentation-build-deploy
+      cancel-in-progress: true
+    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 message
+  pr-preview:
+    needs: [get-date, build, deploy]
+    # If there are open PRs (whose head branch is neither `development` nor `main`), run this job
+    if: ${{ needs.build.outputs.matrix_include != '[]' && ( github.event_name != 'pull_request' || github.event.action != 'closed' ) }}
+    runs-on: ubuntu-latest
+    # Run the same job for each of the open PRs found
+    strategy:
+      matrix:
+        include: ${{ fromJson(needs.build.outputs.matrix_include) }}
+    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 ${{ 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_num }}
+          label: ${{ env.COMMENT_LABEL }}
+
+  failed-preview:
+    needs: [get-date, deploy]
+    # If any job failed (but the workflow was not cancelled) and was fired because of a pull request (not closed)
+    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 }}
+          number: ${{ matrix.pr_num }}
+          label: ${{ env.COMMENT_LABEL }}