Skip to content

Commit 32c27be

Browse files
jcfrjcfr
committed
ci: Add GitHub Workflow to build and publish documentation
1 parent 7714c1a commit 32c27be

File tree

1 file changed

+197
-0
lines changed

1 file changed

+197
-0
lines changed

‎.github/workflows/build-and-publish-doxygen.yml

Lines changed: 197 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
name: Build and Publish
2+
3+
on:
4+
# Allows running this workflow manually from the Actions tab
5+
workflow_dispatch:
6+
inputs:
7+
repository:
8+
description: "Slicer repository for which to build and publish the documentation"
9+
default: Slicer/Slicer
10+
ref:
11+
description: "Slicer branch or tag for which to build and publish the documentation"
12+
default: main
13+
14+
permissions:
15+
# Needed in the publish step to update gh-pages branch
16+
contents: write
17+
18+
jobs:
19+
build-and-publish:
20+
runs-on: ubuntu-latest
21+
steps:
22+
- name: Collect Inputs
23+
id: collect_inputs
24+
run: |
25+
echo "EVENT_NAME [$EVENT_NAME]"
26+
if [[ "$EVENT_NAME" == "workflow_dispatch" ]]; then
27+
repository=${{ github.event.inputs.repository }}
28+
ref=${{ github.event.inputs.ref }}
29+
else
30+
echo "::error ::Unsupported EVENT_NAME [$EVENT_NAME]"
31+
exit 1
32+
fi
33+
echo "repository=$repository" >> $GITHUB_OUTPUT
34+
echo "ref=$ref" >> $GITHUB_OUTPUT
35+
env:
36+
EVENT_NAME: ${{ github.event_name }}
37+
38+
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
39+
with:
40+
repository: ${{ steps.collect_inputs.outputs.repository }}
41+
path: Slicer
42+
ref: ${{ steps.collect_inputs.outputs.ref }}
43+
44+
- name: Determine if ref is branch or tag
45+
id: determine
46+
run: |
47+
cd Slicer
48+
49+
if git show-ref -q --verify "refs/heads/$SLICER_REPO_REF" 2>/dev/null; then
50+
slicer_repo_branch=$SLICER_REPO_REF
51+
echo "slicer_repo_branch [$slicer_repo_branch]"
52+
53+
echo "slicer_repo_branch=$slicer_repo_branch" >> $GITHUB_OUTPUT
54+
exit 0
55+
56+
elif git show-ref -q --verify "refs/tags/$SLICER_REPO_REF" 2>/dev/null; then
57+
slicer_repo_tag=$SLICER_REPO_REF
58+
echo "slicer_repo_tag [$slicer_repo_tag]"
59+
60+
echo "slicer_repo_tag=$slicer_repo_tag" >> $GITHUB_OUTPUT
61+
exit 0
62+
63+
elif git show-ref -q --verify "refs/remote/$SLICER_REPO_REF" 2>/dev/null; then
64+
echo "::error ::Specifying reference as remote [$SLICER_REPO_REF] is not supported"
65+
exit 1
66+
67+
elif git rev-parse --verify "$SLICER_REPO_REF^{commit}" >/dev/null 2>&1; then
68+
echo "::error ::Specifying reference as remote [$SLICER_REPO_REF] is not supported"
69+
exit 1
70+
71+
else
72+
echo "unknown"
73+
exit 1
74+
75+
fi
76+
env:
77+
SLICER_REPO_REF: ${{ steps.collect_inputs.outputs.ref }}
78+
79+
- uses: ssciwr/doxygen-install@527824132256e685f03ec80c0851fe79937eb1d6 # v1.6.3
80+
with:
81+
version: "1.10.0"
82+
83+
# The "dot" binary is provided by Graphviz
84+
- uses: ts-graphviz/setup-graphviz@b1de5da23ed0a6d14e0aeee8ed52fdd87af2363c # v2.0.2
85+
86+
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
87+
with:
88+
repository: Slicer/slicer-apidocs-builder
89+
path: slicer-apidocs-builder
90+
ref: d54050246d989ef93ffd0cb5c73a030aa7c32cd5
91+
92+
- uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
93+
with:
94+
python-version: '3.13'
95+
cache: 'pip'
96+
97+
- name: Install slicer-apidocs-builder
98+
run: |
99+
pip install ./slicer-apidocs-builder
100+
101+
- name: Generate Documentation
102+
id: generate
103+
run: |
104+
WARNING_LOG_FILE=/tmp/Slicer-Slicer-$SLICER_REPO_BRANCH-build/Utilities/Doxygen/UserDoxygenWarnings.txt
105+
mkdir -p $(dirname $WARNING_LOG_FILE)
106+
107+
slicer-apidocs-builder \
108+
--skip-publish \
109+
--slicer-repo-dir $(pwd)/Slicer \
110+
--slicer-repo-branch "$SLICER_REPO_BRANCH" \
111+
--slicer-repo-tag "${SLICER_REPO_TAG}" 2> >(tee $WARNING_LOG_FILE >&2)
112+
113+
echo "warning_log_file=$WARNING_LOG_FILE" >> $GITHUB_OUTPUT
114+
env:
115+
SLICER_REPO_BRANCH: ${{ steps.determine.outputs.slicer_repo_branch }}
116+
SLICER_REPO_TAG: ${{ steps.determine.outputs.slicer_repo_tag }}
117+
118+
- name: Parse and annotate Doxygen warnings
119+
run: |
120+
echo "WARNING_LOG_FILE [$WARNING_LOG_FILE]"
121+
if [[ -f $WARNING_LOG_FILE ]]; then
122+
buffer=""
123+
while IFS= read -r line || [[ -n "$line" ]]; do
124+
# If a buffer exists, prepend the buffered line to this line
125+
if [[ -n "$buffer" ]]; then
126+
line="$buffer$line"
127+
buffer=""
128+
fi
129+
130+
# Extract file, line number, and warning message
131+
FILE=$(echo "$line" | grep -oP "^[^:]+" || true)
132+
LINE=$(echo "$line" | grep -oP ":(\d+):" | tr -d ":" || true)
133+
MESSAGE=$(echo "$line" | grep -oP "warning:.*" || true)
134+
135+
# If MESSAGE is found, process further
136+
if [[ -n "$MESSAGE" ]]; then
137+
MESSAGE=${MESSAGE#warning: } # Strip "warning: " prefix
138+
139+
# Aggregate all subsequent lines starting with at least a space
140+
while IFS= read -r continuation || [[ -n "$continuation" ]]; do
141+
if [[ "$continuation" =~ ^[[:space:]] ]]; then
142+
MESSAGE="${MESSAGE}%0A${continuation}"
143+
else
144+
# Buffer the line to be processed in the main loop
145+
buffer="$continuation"
146+
break
147+
fi
148+
done
149+
fi
150+
151+
# Annotate in GitHub Actions
152+
if [[ -n "$FILE" && -n "$LINE" && -n "$MESSAGE" ]]; then
153+
echo "::warning file=$FILE,line=$LINE::$MESSAGE"
154+
elif [[ -n "$MESSAGE" ]]; then
155+
echo "::warning ::$MESSAGE"
156+
else
157+
echo "Skipped unmatched line: $line"
158+
fi
159+
160+
done < "$WARNING_LOG_FILE"
161+
else
162+
echo "No Doxygen warnings log found."
163+
fi
164+
env:
165+
WARNING_LOG_FILE: ${{ steps.generate.outputs.warning_log_file }}
166+
167+
- uses: actions/create-github-app-token@c1a285145b9d317df6ced56c09f525b5c2b6f755 # v1.11.1
168+
id: app-token
169+
with:
170+
app-id: ${{ vars.SLICER_APP_ID }}
171+
private-key: ${{ secrets.SLICER_APP_PRIVATE_KEY }}
172+
173+
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
174+
with:
175+
ref: gh-pages
176+
path: gh-pages
177+
token: ${{ steps.app-token.outputs.token }}
178+
179+
- name: Publish documentation
180+
run: |
181+
slicer-apidocs-builder \
182+
--skip-build \
183+
--slicer-repo-dir $(pwd)/Slicer \
184+
--slicer-repo-name ${SLICER_REPO_NAME} \
185+
--slicer-repo-branch "${SLICER_REPO_BRANCH}" \
186+
--slicer-repo-tag "${SLICER_REPO_TAG}" \
187+
--publish-github-username "slicer-app[bot]" \
188+
--publish-github-useremail "163601113+slicer-app[bot]@users.noreply.github.com" \
189+
--publish-github-repo-name "Slicer/${PUBLISH_GITHUB_PROJECT_NAME}" \
190+
--publish-github-repo-branch gh-pages \
191+
--publish-github-skip-auth
192+
env:
193+
PUBLISH_GITHUB_PROJECT_NAME: apidocs.slicer.org
194+
SLICER_REPO_NAME: ${{ steps.collect_inputs.outputs.repository }}
195+
SLICER_REPO_BRANCH: ${{ steps.determine.outputs.slicer_repo_branch }}
196+
SLICER_REPO_TAG: ${{ steps.determine.outputs.slicer_repo_tag }}
197+

0 commit comments

Comments
 (0)