diff --git a/.github/workflows/check_links.yml b/.github/workflows/check_links.yml
new file mode 100644
index 0000000..d2178a3
--- /dev/null
+++ b/.github/workflows/check_links.yml
@@ -0,0 +1,30 @@
+# =========== IMPORTANT!! READ THIS!! ============ #
+# This file is used to check links and can be copied to be used in other websites.
+
+# When you copy this file, make sure to check and modify the fields
+# that here are marked with `MODIFY`.
+# ============================================== #
+
+name: Check links
+
+on:
+ push:
+ branches:
+ - main
+ pull_request:
+ types: [opened, synchronize, reopened]
+ workflow_dispatch:
+
+jobs:
+ check-links:
+ uses: access-nri/access-hive-docs/.github/workflows/check_links_workflow.yml@main
+ with:
+ repo: '${{ github.repository }}'
+ ref_name: "${{ github.event_name == 'pull_request' && format('refs/pull/{0}/head', github.event.pull_request.number) || github.ref_name }}"
+ rtd_project: 'access-cm3-configs' # MODIFY: change this to the Read the Docs project
+ python_requirements_txt: 'documentation/requirements.txt' # MODIFY: Uncomment to add requirements.txt path. If not included, 'requirements.txt' is used.
+ mkdocs_yaml: 'documentation/mkdocs.yml' # MODIFY: Uncomment to add mkdocs.yml path. If not included, 'mkdocs.yml' is used.
+ # lychee_config: '/path/to/lychee_config.toml' # MODIFY: Uncomment to add lychee config path. If not included, the Hive Docs' one gets used.
+ # # MODIFY: Uncomment the lines below if the repo is private. You also need to create a secret named REPO_READ_TOKEN with a token that has repo read permissions.
+ # secrets:
+ # repo_read_token: ${{ secrets.REPO_READ_TOKEN }}
\ No newline at end of file
diff --git a/.github/workflows/delete_pr_preview_comment.yml b/.github/workflows/delete_pr_preview_comment.yml
index 5c19a91..b5277aa 100644
--- a/.github/workflows/delete_pr_preview_comment.yml
+++ b/.github/workflows/delete_pr_preview_comment.yml
@@ -1,475 +1,21 @@
-# =========== 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
+name: Delete PR preview comment
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
+ pull_request:
types:
- - opened
- - reopened
- - synchronize
- workflow_dispatch: #Action can also be triggered manually
+ - closed
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() }}
+ # Delete PR preview comment
+ delete-pr-preview-comment:
+ name: Delete PR preview comment
runs-on: ubuntu-latest
permissions:
pull-requests: write
steps:
- - name: Add PR preview failure comment
+ - name: Remove PR preview 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 }}
+ delete: true
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
index 9584176..7897f6c 100644
--- a/.github/workflows/deploy_to_github_pages.yml
+++ b/.github/workflows/deploy_to_github_pages.yml
@@ -1,30 +1,41 @@
+# =========== 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/
+# - .github/workflows/delete_pr_preview.yml
+# ============================================== #
+
name: Deploy to GitHub Pages
on:
- push: #Action fires anytime there is a push to the following branches
+ 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
+ - '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
+ workflow_dispatch: # Action can also be triggered manually
env:
TZ: Australia/Canberra
- DOC_DIR: 'documentation'
+ 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
+ PR_PREVIEW_EXCLUDE_REGEX: ^!no-(pr-)?preview\b # This regex will be considered case insensitive
PR_PREVIEW_COMMENT_LABEL: pr-preview-comment
- BUILD_DEVELOPMENT_WEBSITE: false
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
@@ -38,7 +49,7 @@ jobs:
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
+ # Get the root url to be used at build time to set the READTHEDOCS_CANONICAL_URL env variable
# used in the mkdocs.yml file to construct the website map for links
get-root-url:
name: Set root URL
@@ -145,7 +156,7 @@ jobs:
run: |
dir=
site_url="${{ env.ROOT_URL }}${dir:+${dir}/}"
- command="SITE_URL=${site_url} mkdocs build -f mkdocs.yml -d ${{env.BUILD_DIR}}"
+ command="READTHEDOCS_CANONICAL_URL=${site_url} mkdocs build -f mkdocs.yml -d ${{env.BUILD_DIR}}"
echo "$command"
eval "$command"
@@ -202,7 +213,7 @@ jobs:
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}}"
+ command="READTHEDOCS_CANONICAL_URL=${site_url} mkdocs build -f mkdocs.yml -d ${{env.BUILD_DIR}}"
echo "$command"
eval "$command"
@@ -237,7 +248,7 @@ jobs:
gh pr list \
--state open \
--json number,title,headRepositoryOwner,headRefOid,body \
- --jq 'sort_by(.number) | .[] | select( .headRefName!="main" and .headRepositoryOwner.login=="ACCESS-NRI")' \
+ --jq 'sort_by(.number) | .[] | select( .headRefName!="main" and .headRepositoryOwner.login=="${{ github.repository_owner }}")' \
)
# If open PRs are found, filter them and output the desired json object
@@ -319,7 +330,7 @@ jobs:
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}}"
+ command="READTHEDOCS_CANONICAL_URL=${site_url} mkdocs build -f mkdocs.yml -d ${{env.BUILD_DIR}}"
echo "$command"
eval "$command"
@@ -351,7 +362,13 @@ jobs:
- name: Create PR previews page
run: |
- printf '{"data": %s}' '${{ needs.get-prs-info.outputs.open_prs_info }}' | \
+ open_prs_json='${{ needs.get-prs-info.outputs.open_prs_info }}'
+ if [[ -n "$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 }}
@@ -405,7 +422,7 @@ jobs:
# 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() }}
+ if: ${{ always() && needs.set-website-structure.result == 'success' }}
permissions:
pages: write # to deploy to Pages
id-token: write # to verify the deployment originates from an appropriate source
@@ -417,7 +434,7 @@ jobs:
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 != '' }}
+ if: ${{ always() && needs.deploy.result == 'success' && needs.get-prs-info.outputs.open_prs_info != '' }}
runs-on: ubuntu-latest
strategy:
fail-fast: false
@@ -455,4 +472,4 @@ jobs:
⚠️ 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
+ label: ${{ env.PR_PREVIEW_COMMENT_LABEL }}
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
diff --git a/documentation/hooks/hide_pages_url_segment.py b/documentation/hooks/hide_pages_url_segment.py
index bb7f074..56b4b0f 100644
--- a/documentation/hooks/hide_pages_url_segment.py
+++ b/documentation/hooks/hide_pages_url_segment.py
@@ -4,6 +4,8 @@
@event_priority(-100)
def on_page_markdown(markdown, *, page, config, files):
if page.file.url.startswith("pages/"):
+ # Remove "pages/" prefix from the URL
page.file.url = page.file.url.removeprefix("pages/")
page.file.dest_uri = page.file.dest_uri.removeprefix("pages/")
- page.file.abs_dest_path = page.file.abs_dest_path.removeprefix("pages/")
\ No newline at end of file
+ page.file.abs_dest_path = page.file.abs_dest_path.removeprefix("pages/")
+ page.canonical_url = config.site_url + page.file.url
\ No newline at end of file
diff --git a/documentation/mkdocs.yml b/documentation/mkdocs.yml
index a9421c9..869c9e5 100755
--- a/documentation/mkdocs.yml
+++ b/documentation/mkdocs.yml
@@ -4,7 +4,7 @@
site_name: access-cm3-configs
# Site URL
-site_url: !ENV [SITE_URL, "http://access-nri.github.io/access-cm3-configs/"]
+site_url: !ENV READTHEDOCS_CANONICAL_URL
# Git repository (Adds a link to the GitHub repository at the top)
repo_url: https://github.com/ACCESS-NRI/access-cm3-configs
@@ -63,8 +63,6 @@ plugins:
- bibtex:
bib_file: references.bib
csl_file: https://raw.githubusercontent.com/citation-style-language/styles/26eccff9e537f71494a4da7b91afac1adf571dc9/apa.csl
- - events:
- events_dir: community_resources/events/events
markdown_extensions:
- attr_list
diff --git a/documentation/requirements.txt b/documentation/requirements.txt
index 42f7524..f6e73f9 100644
--- a/documentation/requirements.txt
+++ b/documentation/requirements.txt
@@ -3,4 +3,4 @@ mkdocs-git-revision-date-localized-plugin==1.2.0
mkdocs-macros-plugin==1.0.4
mkdocs-bibtex==4.4.0
pypandoc_binary==1.15
-git+https://github.com/rbeucher/mkdocs_events_plugin.git
\ No newline at end of file
+git+https://github.com/ACCESS-NRI/mkdocs_resolve_absolute_urls_plugin.git@1.2.0
\ No newline at end of file