Skip to content

Commit 5a8dc23

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

File tree

1 file changed

+191
-0
lines changed

1 file changed

+191
-0
lines changed

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

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

0 commit comments

Comments
 (0)