-
Notifications
You must be signed in to change notification settings - Fork 47
216 lines (188 loc) · 8.44 KB
/
build_and_deploy_docs.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
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
#
# GitHub Actions Workflow for building and publishing the CF conventions and
# conformance docs.
#
# For more information on the actions used in this workflow, please see:
# https://github.com/actions/checkout
# https://github.com/Analog-inc/asciidoctor-action
# https://github.com/actions/upload-artifact
# https://github.com/actions/download-artifact
# https://github.com/marocchino/sticky-pull-request-comment
name: Asciidoctor Build Workflow
on:
workflow_dispatch: # Manual trigger
pull_request: # On pull request
push: # On push any branch (excluding gh-pages)
branches-ignore: [gh-pages]
release: # On release published
types:
- published
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
contents: write
pages: write
id-token: write
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
group: "pages"
cancel-in-progress: false
env:
DESIRED_BRANCH: "gh-pages" # Branch to use for GitHub Pages
DESIRED_PATH: "/" # Path to use for GitHub Pages
DESIRED_BUILD_TYPE: "legacy" # Build type for GitHub Pages
GH_TOKEN: ${{ github.token }}
jobs:
# Job to build documents
build_docs:
name: Build Documentation
runs-on: ubuntu-latest
if: ${{ !(github.event_name == 'pull_request' && github.event.action == 'closed') }}
steps:
- name: Checkout Repository
uses: actions/checkout@v4
- name: Set Release Tag and Date
if: github.event_name == 'release'
run: |
echo "CF_FINAL=True" >> $GITHUB_ENV
- name: Build Documentation
uses: Analog-inc/asciidoctor-action@v1
with:
shellcommand: 'make all'
- name: Upload Artifacts
uses: actions/upload-artifact@v4
with:
name: documentation_artifacts
path: build/
- name: Output Artifact Link for PR
if: ${{ github.event_name == 'pull_request' }}
run: |
echo "Artifacts for this PR can be downloaded from the following link:"
echo "https://${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}/"
echo "::notice::[Download Artifacts](https://${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}/)"
# Job to publish documentation to GitHub Pages and as assests on release page
publish_docs:
name: Publish Documentation
runs-on: ubuntu-latest
needs: build_docs
if: ${{ github.event_name != 'pull_request' }} # Skip this job if the event is a PR
steps:
- name: Verify Pre-installed Tools
run: |
jq --version
tree --version
gh --version
- name: Checkout Repository
uses: actions/checkout@v4
- name: Check and Create GH Pages Branch
run: |
if ! git ls-remote --exit-code origin gh-pages > /dev/null; then
echo "Creating the $DESIRED_BRANCH branch..."
git checkout --orphan $DESIRED_BRANCH
git rm -rf . || true
echo "# GitHub Pages" > index.html
git add index.html
git commit -m "Initialize $DESIRED_BRANCH branch"
git push origin $DESIRED_BRANCH
else
echo "The $DESIRED_BRANCH branch already exists."
fi
- name: Enforce GitHub Pages Configuration
run: |
# Fetch current GitHub Pages configuration
API_RESPONSE=$(gh api repos/${{ github.repository }}/pages || echo "{}")
# Extract current configuration
IS_ENABLED=$(echo "$API_RESPONSE" | jq -r '.source // empty')
BUILD_TYPE=$(echo "$API_RESPONSE" | jq -r '.build_type // empty')
SOURCE_BRANCH=$(echo "$API_RESPONSE" | jq -r '.source.branch // empty')
SOURCE_PATH=$(echo "$API_RESPONSE" | jq -r '.source.path // empty')
# Enforce configuration if any setting is incorrect or GitHub Pages is not enabled
if [[ -z "$IS_ENABLED" ]] || [[ "$BUILD_TYPE" != "$DESIRED_BUILD_TYPE" ]] || [[ "$SOURCE_BRANCH" != "$DESIRED_BRANCH" ]] || [[ "$SOURCE_PATH" != "$DESIRED_PATH" ]]; then
echo "Enforcing GitHub Pages configuration..."
gh api repos/${{ github.repository }}/pages \
--method POST \
--input - <<< "{\"source\":{\"branch\":\"$DESIRED_BRANCH\",\"path\":\"$DESIRED_PATH\"}, \"build_type\":\"$DESIRED_BUILD_TYPE\"}"
echo "GitHub Pages has been configured: Branch='${DESIRED_BRANCH}', Path='${DESIRED_PATH}', Build Type='${DESIRED_BUILD_TYPE}'."
else
echo "GitHub Pages is already configured correctly: Branch='${DESIRED_BRANCH}', Path='${DESIRED_PATH}', Build Type='${DESIRED_BUILD_TYPE}'."
fi
- name: Checkout gh-pages Branch into Subdirectory
uses: actions/checkout@v4
with:
repository: ${{ github.repository }}
ref: ${{ env.DESIRED_BRANCH }}
path: gh-pages
- name: Determine Target Directory and Add .nojekyll
run: |
cd gh-pages
# Ensure .nojekyll exists
[ ! -f .nojekyll ] && touch .nojekyll
# Determine target directory based on the event type
if [[ ${{ github.event_name }} == 'release' ]]; then
echo "TARGET_DIR=release/${GITHUB_REF_NAME}" >> $GITHUB_ENV
elif [[ ${{ github.event_name }} == 'pull_request' ]]; then
PR_NUMBER=${{ github.event.pull_request.number }}
echo "TARGET_DIR=pr-preview/${PR_NUMBER}" >> $GITHUB_ENV
elif [[ ${{ github.ref_name }} == '${{ github.event.repository.default_branch }}' ]]; then
echo "TARGET_DIR=./" >> $GITHUB_ENV
else
echo "TARGET_DIR=${GITHUB_REF_TYPE}/${GITHUB_REF_NAME}" >> $GITHUB_ENV
fi
- name: Download Artifacts
uses: actions/download-artifact@v4
with:
name: documentation_artifacts
path: gh-pages/build/
- name: Verify Build Artifacts
run: |
cd gh-pages
if [ ! "$(ls -A build)" ]; then
echo "Build artifacts are missing!" >&2
exit 1
fi
- name: Publish Documentation
if: ${{ !(github.event_name == 'pull_request' && github.event.action == 'closed') }}
run: |
cd gh-pages
mkdir -p ${{ env.TARGET_DIR }}
cp -p build/* ${{ env.TARGET_DIR }}/
rm -rf build/
- name: Prepare and Update Index Page
run: |
cd gh-pages
sudo cp -p ../.github/gh-pages/index.html ${{ env.TARGET_DIR }}/
COMMIT_DATE=$(git show -s --format=%cd --date=format:'%Y-%m-%dT%H:%M:%SZ')
if [[ "${GITHUB_REF_NAME}" != "${{ github.event.repository.default_branch }}" ]]; then
PATH_REVISION="${GITHUB_REPOSITORY}/${GITHUB_REF_TYPE}/${GITHUB_REF_NAME}@${GITHUB_SHA:0:7}"
sudo sed -i "s/Latest/${PATH_REVISION//\//\\/}/" ${{ env.TARGET_DIR }}/index.html
else
echo "Push is to the default branch; Latest build"
fi
- name: Cleanup PR Artifacts
if: ${{ github.event_name == 'pull_request' && github.event.action == 'closed' }}
run: |
cd gh-pages
rm -rf ${{ env.TARGET_DIR }}
- name: Build Index Tree
run: |
cd gh-pages
tree -T "${GITHUB_REPOSITORY}" --dirsfirst --prune --noreport \
-I "index.html|README.md" -H . -o index.html
- name: Commit and Push Changes
run: |
cd gh-pages
git add --all
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
git commit -m "Update documentation from ${GITHUB_REPOSITORY}@${GITHUB_SHA}" || echo "No changes to commit; skipping push."
git push
- name: Upload Documentation files as Release Asset
if: github.event_name == 'release'
run: |
export TARGET_DIR=${{ env.TARGET_DIR }}
gh release upload ${{ github.event.release.tag_name }} \
gh-pages/${TARGET_DIR}/cf-conventions.html \
gh-pages/${TARGET_DIR}/cf-conventions.pdf \
gh-pages/${TARGET_DIR}/conformance.html \
gh-pages/${TARGET_DIR}/conformance.pdf \
--clobber