Skip to content

Commit eecb16f

Browse files
chrisb13chrisb13
committed
first go at wombat docs!
1 parent 799b956 commit eecb16f

38 files changed

+3486
-0
lines changed

‎.github/workflows/deploy_to_github_pages.yml‎

Lines changed: 238 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,238 @@
1+
name: Deploy to GitHub Pages
2+
on:
3+
push: #Action fires anytime there is a push to the following branches
4+
branches:
5+
- main
6+
paths:
7+
- documentation/**
8+
pull_request: #Action also fires anytime a PR is (re)opened, closed or synchronized
9+
types:
10+
- opened
11+
- reopened
12+
- synchronize
13+
- closed
14+
paths:
15+
- documentation/**
16+
workflow_dispatch: #Action can also be triggered manually
17+
env:
18+
TZ: Australia/Canberra
19+
DOC_DIR: documentation
20+
ROOT_BUILD_DIR: ${{ github.workspace }}/website
21+
COMMENT_LABEL: pr-preview
22+
ROOT_DOMAIN: https://access-nri.github.io
23+
24+
jobs:
25+
set-root-url:
26+
runs-on: ubuntu-latest
27+
outputs:
28+
root_url: ${{ steps.set-root-url.outputs.root_url }}
29+
steps:
30+
- name: Set root url
31+
id: set-root-url
32+
run: |
33+
if [[ ${{ env.ROOT_DOMAIN }} == https://access-nri.github.io ]]; then
34+
root_url=${{ env.ROOT_DOMAIN }}/${{ github.event.repository.name }}
35+
else
36+
root_url=${{ env.ROOT_DOMAIN }}
37+
fi
38+
echo "Root url set to ${root_url}"
39+
echo "root_url=${root_url}" >> $GITHUB_OUTPUT
40+
41+
get-date:
42+
runs-on: ubuntu-latest
43+
env:
44+
TZ: Australia/Canberra
45+
outputs:
46+
date: ${{ steps.get-date.outputs.date }}
47+
steps:
48+
- name: Get date
49+
id: get-date
50+
run: echo "date=$(date '+%Y-%m-%d %H:%M %Z')" >> $GITHUB_OUTPUT
51+
52+
pr-preview-setup:
53+
# Run this job only if the action was fired because of a PR
54+
if: ${{ github.event_name == 'pull_request' }}
55+
needs: get-date
56+
runs-on: ubuntu-latest
57+
env:
58+
HEAD: ${{ github.event.pull_request.head.sha }}
59+
HEAD_URL: https://github.com/${{ github.event.pull_request.head.repo.full_name }}/commit/${{ github.event.pull_request.head.sha }}
60+
permissions:
61+
pull-requests: write
62+
steps:
63+
- name: Add PR preview setup comment
64+
if: ${{ github.event.action != 'closed' }}
65+
uses: access-nri/actions/.github/actions/comment@main
66+
with:
67+
message: |
68+
PR Preview
69+
:---:
70+
🛫 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.
71+
${{ needs.get-date.outputs.date }}
72+
label: ${{ env.COMMENT_LABEL }}
73+
74+
- name: Remove PR preview comment
75+
if: ${{ github.event.action == 'closed' }}
76+
uses: access-nri/actions/.github/actions/comment@main
77+
with:
78+
delete: true
79+
label: ${{ env.COMMENT_LABEL }}
80+
81+
build:
82+
# Cancel any previous build/deploy jobs that are still running (no need to build/deploy multiple times)
83+
concurrency:
84+
group: documentation-build-deploy
85+
cancel-in-progress: true
86+
runs-on: ubuntu-latest
87+
needs: set-root-url
88+
outputs:
89+
matrix_include: ${{ steps.build-pr-preview.outputs.matrix_include }}
90+
if: ${{ ! ( github.event_name == 'pull_request' && github.event.action == 'closed' ) }}
91+
steps:
92+
- name: Checkout
93+
uses: actions/checkout@v4
94+
95+
- name: Python setup
96+
uses: actions/setup-python@v5
97+
with:
98+
python-version: 3.11.x
99+
100+
- name: Install dependencies
101+
working-directory: ${{ env.DOC_DIR }}
102+
run: |
103+
pip install -r requirements.txt
104+
105+
- name: Build main website
106+
working-directory: ${{ env.DOC_DIR }}
107+
env:
108+
GH_TOKEN: ${{ github.token }} # Required for gh usage
109+
ROOT_URL: ${{ needs.set-root-url.outputs.root_url }}
110+
run: |
111+
echo "::group::Build main website"
112+
git fetch origin main
113+
git checkout main
114+
if [[ -f mkdocs.yml ]]; then
115+
dir=
116+
site_url=${{ env.ROOT_URL }}/${dir}
117+
build_dir=${{ env.ROOT_BUILD_DIR }}/${dir}
118+
command="SITE_URL=${site_url} mkdocs build -f mkdocs.yml -d ${build_dir}"
119+
echo "$command"
120+
eval "$command"
121+
else
122+
echo "::warning::No configuration found in the 'main' branch."
123+
fi
124+
echo "::endgroup::"
125+
126+
- name: Build PR previews
127+
working-directory: ${{ env.DOC_DIR }}
128+
env:
129+
GH_TOKEN: ${{ github.token }} # Required for gh usage
130+
ROOT_URL: ${{ needs.set-root-url.outputs.root_url }}
131+
id: build-pr-preview
132+
run: |
133+
echo "::group::Build PR previews"
134+
git fetch --all -Pp
135+
# Include only open PRs, not from forks, and whose head branch is not `main`
136+
open_pr_info=$(gh pr list \
137+
--state open \
138+
--json headRepositoryOwner,headRefOid,number,headRefName \
139+
--jq '.[] | select( .headRefName!="main" and .headRepositoryOwner.login=="ACCESS-NRI")' \
140+
)
141+
pr_nums=($(jq '.number' <<< "$open_pr_info"))
142+
if [[ -n $pr_nums ]]; then
143+
echo "Found the following open PRs: $(IFS=, ; echo "${pr_nums[*]}")."
144+
for num in ${pr_nums[@]}; do
145+
echo "::group::Build PR preview for PR #${num}"
146+
gh pr checkout $num
147+
if [[ -f mkdocs.yml ]]; then
148+
dir=pr-preview-${num}
149+
site_url=${{ env.ROOT_URL }}/${dir}
150+
build_dir=${{ env.ROOT_BUILD_DIR }}/${dir}
151+
command="SITE_URL=${site_url} mkdocs build -f mkdocs.yml -d ${build_dir}"
152+
echo "$command"
153+
eval "$command"
154+
# Defining the json string for the matrix.include field used in the pr-preview job
155+
# Defining the following fields:
156+
# - pr_num: the PR number
157+
# - pr_preview_url: the URL of the PR preview
158+
# - pr_head_sha: the SHA of the commit in the PR head
159+
json_array+=("{\"pr_num\":${num},\"pr_preview_url\":\"${site_url}\",\"pr_head_sha\":\"$(git rev-parse HEAD)\"}")
160+
else
161+
echo "::warning::No configuration found in the PR #${num} head."
162+
fi
163+
echo '::endgroup::'
164+
done
165+
# Create the json for the matrix.include from the json_array
166+
matrix_include=$(jq -c <<< "[$(IFS=, ; echo "${json_array[*]}")]")
167+
echo "matrix_include=${matrix_include}" >> "$GITHUB_OUTPUT"
168+
else
169+
echo "No open PR found."
170+
fi
171+
echo '::endgroup::'
172+
173+
- name: Set permissions
174+
run: chmod -c -R +rX ${{ env.ROOT_BUILD_DIR }}
175+
176+
- name: Create artifact for deployment to GitHub Pages
177+
uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa #v3.0.1
178+
with:
179+
path: ${{ env.ROOT_BUILD_DIR }}
180+
181+
deploy:
182+
needs: build
183+
runs-on: ubuntu-latest
184+
# Cancel any previous build/deploy jobs that are still running (no need to build/deploy multiple times)
185+
concurrency:
186+
group: documentation-build-deploy
187+
cancel-in-progress: true
188+
permissions:
189+
pages: write # to deploy to Pages
190+
id-token: write # to verify the deployment originates from an appropriate source
191+
steps:
192+
- name: Deploy to GitHub Pages
193+
uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e #v4.0.5
194+
195+
# Set pr-preview message
196+
pr-preview:
197+
needs: [get-date, build, deploy]
198+
# If there are open PRs (whose head branch is neither `development` nor `main`), run this job
199+
if: ${{ needs.build.outputs.matrix_include != '[]' && ( github.event_name != 'pull_request' || github.event.action != 'closed' ) }}
200+
runs-on: ubuntu-latest
201+
# Run the same job for each of the open PRs found
202+
strategy:
203+
matrix:
204+
include: ${{ fromJson(needs.build.outputs.matrix_include) }}
205+
permissions:
206+
pull-requests: write
207+
steps:
208+
- name: Add PR preview setup comment
209+
uses: access-nri/actions/.github/actions/comment@main
210+
with:
211+
message: |
212+
PR Preview
213+
:---:
214+
🚀 Preview of PR head ${{ matrix.pr_head_sha }} deployed to ${{ matrix.pr_preview_url }}
215+
${{ needs.get-date.outputs.date }}
216+
Preview generated through the ${{ github.workflow }} workflow run [${{ github.run_id }}](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}).
217+
number: ${{ matrix.pr_num }}
218+
label: ${{ env.COMMENT_LABEL }}
219+
220+
failed-preview:
221+
needs: [get-date, deploy]
222+
# If any job failed (but the workflow was not cancelled) and was fired because of a pull request (not closed)
223+
if: ${{ github.event_name == 'pull_request' && failure() }}
224+
runs-on: ubuntu-latest
225+
permissions:
226+
pull-requests: write
227+
steps:
228+
- name: Add PR preview failure comment
229+
uses: access-nri/actions/.github/actions/comment@main
230+
with:
231+
message: |
232+
PR Preview
233+
:---:
234+
⚠️ There was an error in the pr-preview deployment.
235+
For more information check the [Actions](https://github.com/${{github.repository}}/actions) tab.
236+
${{ needs.get-date.outputs.date }}
237+
number: ${{ matrix.pr_num }}
238+
label: ${{ env.COMMENT_LABEL }}

‎documentation/.mkdocs.yml.un~‎

45.3 KB
Binary file not shown.

‎documentation/docs/.index.md.un~‎

23.2 KB
Binary file not shown.

‎documentation/docs/assets/ACCESS_icon_HIVE.png‎

32 KB
Loading

‎documentation/docs/assets/WW3_workflow.png‎

536 KB
Loading

‎documentation/docs/assets/nuopc_overview.png‎

111 KB
Loading

0 commit comments

Comments
 (0)