-
Notifications
You must be signed in to change notification settings - Fork 1
184 lines (161 loc) · 6.95 KB
/
docs_build_and_deploy.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
name: Build Sphinx docs and deploy to GitHub Pages
# Generate the documentation on all merges to main, all pull requests, or by
# manual workflow dispatch. The build job can be used as a CI check that the
# docs still build successfully. The deploy job only runs when a tag is pushed
# (so, when a new release is made).
on:
push:
branches:
- main
tags:
- '*'
pull_request:
workflow_dispatch:
jobs:
linting:
# scheduled workflows should not run on forks
if: (${{ github.event_name == 'schedule' }} && ${{ github.repository_owner == 'neuroinformatics-unit' }} && ${{ github.ref == 'refs/heads/main' }}) || (${{ github.event_name != 'schedule' }})
runs-on: ubuntu-latest
steps:
- uses: neuroinformatics-unit/actions/lint@v2
build_sphinx_docs:
name: Build Sphinx Docs
needs: linting
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
# Need the tags so that setuptools-scm can form a valid version number
- name: Fetch git tags
run: git fetch origin 'refs/tags/*:refs/tags/*'
- name: Setup Python
uses: actions/setup-python@v5
with:
python-version: ${{ inputs.python-version }}
- name: Upgrade pip
shell: bash
run: |
# install pip=>20.1 to use "pip cache dir"
python3 -m pip install --upgrade pip
- name: Get pip cache dir
shell: bash
id: pip-cache
run: echo "dir=$(pip cache dir)" >> $GITHUB_OUTPUT
- name: Cache dependencies
uses: actions/cache@v4
with:
path: ${{ steps.pip-cache.outputs.dir }}
key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
restore-keys: |
${{ runner.os }}-pip-
- name: Install dependencies
shell: bash
run: python3 -m pip install -r ./docs/requirements.txt
- name: Check links
shell: bash
run: |
sphinx-build docs/source docs/build -b linkcheck
# needs to have sphinx.ext.githubpages in conf.py extensions list
- name: Building documentation
shell: bash
run: |
sphinx-build docs/source docs/build -b html -W --keep-going
- name: Upload the content for deployment
uses: actions/upload-artifact@v4
with:
name: docs-${{ github.sha }}
path: ./docs/build/
deploy_sphinx_docs:
name: Deploy Sphinx Docs
needs: build_sphinx_docs
permissions:
contents: write
if: github.event_name == 'push'
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
# Fetch the built docs from the "build_sphinx_docs" job
- name: Download HTML documentation artifact
uses: actions/download-artifact@v4
with:
name: docs-${{ github.sha }}
path: docs/build
- name: Checkout the gh-pages branch in a separate folder
uses: actions/checkout@v4
with:
ref: gh-pages
# Checkout to this folder instead of the current one
path: deploy
# Download the entire history
fetch-depth: 0
- name: Push the built HTML to gh-pages
run: |
# Detect if this is a release or from the main branch
echo "Event name: ${{ github.event_name }}"
echo "Ref type: ${{ github.ref_type }}"
if [ "${{ github.event_name }}" = "push" ] && [ "${{ github.ref_type }}" = "tag" ]; then
# Get the tag name without the "refs/tags/" part
version="${GITHUB_REF#refs/*/}"
else
version=dev
fi
echo "Deploying version: $version"
# Make the new commit message. Needs to happen before cd into deploy
# to get the right commit hash.
message="Deploy $version from $(git rev-parse --short HEAD)"
cd deploy
# Need to have this file so that Github doesn't try to run Jekyll
touch .nojekyll
# Delete all the files and replace with our new set
echo -e "\nRemoving old files from previous builds of ${version}:"
rm -rvf ${version}
echo -e "\nCopying HTML files to ${version}:"
cp -Rvf ../docs/build ${version}/
if [[ "${version}" != "dev" ]]; then
# Updated switcher.json file
SWITCHER_CONTENT=$(curl https://neuroblueprint.neuroinformatics.dev/latest/_static/switcher.json)
BASE_URL="$(jq -r '.[1].url|split("/")[0:3]|join("/")' <<< $SWITCHER_CONTENT)"
NEW_URL="${BASE_URL}/latest/"
# Extract the current latest version entry
FIRST_ENTRY=$(jq '.[0]' <<< "${SWITCHER_CONTENT}")
CURRENT_LATEST_VERSION=$(echo $(jq '.[1].version' <<< "${SWITCHER_CONTENT}") | tr -d '"')
# Remove the "name" field from the current latest entry
UPDATED_CURRENT_LATEST_ENTRY=$(jq --arg url "${BASE_URL}/${CURRENT_LATEST_VERSION}" '.[1] | .url = $url | del(.name)' <<< "$SWITCHER_CONTENT")
# Create the new version entry with the "latest" tag
NEW_ENTRY=$(jq -n --arg version "${version}" --arg url "$NEW_URL" --arg name "$version (latest)" \
'{name: $name, version: $version, url: $url}')
# Combine the entries in the desired order
UPDATED_SWITCHER_CONTENT=$(jq --argjson first_entry "$FIRST_ENTRY" --argjson new_entry "$NEW_ENTRY" --argjson updated_current_latest "$UPDATED_CURRENT_LATEST_ENTRY" '[$first_entry, $new_entry, $updated_current_latest] + .[2:]' <<< "$SWITCHER_CONTENT")
# Write the updated content back to switcher.json
echo "$UPDATED_SWITCHER_CONTENT" > "$SWITCHER_FILE"
echo "switcher.json has been updated successfully."
fi
# If this is a new release, update the link from /latest to it
if [[ "${version}" != "dev" ]]; then
echo -e "\nSetup link from ${version} to 'latest'."
rm -f latest
ln -sf ${version} latest
fi
# Stage the commit
git add -A .
echo -e "\nChanges to be applied:"
git status
# Configure git to be the GitHub Actions account
git config user.email "github-actions[bot]@users.noreply.github.com"
git config user.name "github-actions[bot]"
# If this is a dev build and the last commit was from a dev build
# (detect if "dev" was in the previous commit message), reuse the
# same commit
if [[ "${version}" == "dev" && `git log -1 --format='%s'` == *"dev"* ]]; then
echo -e "\nAmending last commit:"
git commit --amend --reset-author -m "$message"
else
echo -e "\nMaking a new commit:"
git commit -m "$message"
fi
# Make the push quiet just in case there is anything that could leak
# sensitive information.
echo -e "\nPushing changes to gh-pages."
git push -fq origin gh-pages 2>&1 >/dev/null
echo -e "\nFinished uploading generated files."